Documenting scores

Overview

Each composite and leaf score may include a Document element in its definition whose main purpose is to provide detailed documentation for the score when it is displayed in a score tab in either the user view or the device view.

The documentation of a score optionally holds:

• Links to other HTTP resources.

• Links to remote actions (must allow manual triggering).

This article assumes that you are acquainted with writing definitions of scores in XML format and specifically focuses in documenting your scores.

Document structure

The Document element is an optional XML element that you can find at the end of the definition of a composite or a leaf score.

The Document element has the following structure:

• A Header.

• A list of Sections.

<Document>
  <Header>[<Main documentation header>]</Header>
  <!-- List of sections -->
  <Sections>
    <Section>...</Section>
    ...
  </Sections>
</Document>

Both the header and the list of sections are optional, but the documentation of a score is only as useful as the content provided in these elements.

Document sections

In turn, each section in the list includes a title, followed by an optional sequence of descriptions, HTTP links, and links to remote actions. Typically, precede each link or group of links by a description that explains their purpose.

<Section>
  <Title>[Title for the section]</Title>
  <Description>[Text describing the contents]</Description>
  <RemoteAction ... />
  <HTTP ... />
  ...
</Section>

Add as many descriptions, remote actions, and HTTP links to the section as you need, in the order that suits you best.

Adding HTTP links

To add an HTTP link, provide the destination URL in the href attribute and, optionally, a text to show in place of the URL:

<HTTP href="http(s)://url">[Text for the link]</HTTP>

Adding links to remote actions

To add a link to a remote action that allows manual triggering, provide the unique identifier (UID) of the remote action:

<RemoteAction UID="[identifier]" />

To get the UID of a remote action:

1. Log in to the Finder as a user with the permission to edit remote actions.

2. Locate the desired remote action in the Remote actions section of the left-hand side panel.

3. Right-click the remote action name.

4. Select Export > Remote action to clipboard.

5. Open your favorite XML or plain text editor.

6. Press Ctrl+V to paste the contents of the clipboard on the editor.

7. Find the UID attribute of the Action element in the XML of the remote action.

The Finder uses the name of the remote action as the text for the link and precedes the link with the characteristic rocket icon of remote actions.

It only makes sense to add remote actions to the documentation of scores that apply to devices and not to users.

Rendering example

The Finder displays the documentation elements of a score as follows:

RELATED REFERENCE

• Score XML Reference