Accessing Topics

Many elements in the HelpTag language support an ID attribute. An ID is a unique name used internally to identify topics and elements within topics. An ID is defined only once, but multiple hyperlinks and cross-references can refer to the same ID. IDs are not seen by the user.

If you are writing help for an application, IDs are also used by the application to identify particular topics to display when the user requests help. For example, you might write several topics that describe an application's menus. The IDs that you assign to the topics are used by the application developer. By defining identical IDs within the application code, the developer can integrate specific topics. This allows the application to access and display the correct topic when help is requested for a particular menu.

Rules for ID Names

• ID strings may contain letters (A - Z and a - z), digits (0 - 9), and the minus (-) sign, and must begin with a letter.

• Author-defined IDs may not use the _ (underscore character); it is reserved for IDs that are built into some HelpTag elements.

• Case is not significant, but is often used to increase readability.

• ID strings cannot be longer than 64 characters.

• Each ID within a single help volume must be unique.

To Add an ID to a Topic

Use the id parameter for the element as follows:

<element id=id>  ...

The elements that start a new topic and support an author-defined ID are:

• <chapter id=id>

• <otherfront id=id>

• <rsect id=id>

• <s1 id=id>

• <s2 id=id> . . .<s9 id=id>

Built-in IDs

A few elements have built-in IDs and, therefore, do not support an author-defined ID. Each of the following elements also starts a new topic, but these elements have predefined IDs (shown in parentheses):

<abstract>

(_abstract)

<copyright>

(_copyright)

<glossary>

(_glossary)

<hometopic>

(_hometopic)

<title>

(_title)

To Add an ID to an Element Within a Topic

If the element supports an author-defined ID, use the id parameter for the element as follows:

<element id=id>  ...

The elements (within a topic) that support an ID attribute are:

• <figure id=id>

• <graphic id=id>

• <image id=id>

• <location id=id>

• <p id=id>

Or, use the <location> element to set an ID at an arbitrary point within the topic as follows:

<location id=id> text <\location> 

Where text is any word or phrase where you want to add an ID. The <\location> end tag is required. When you activate a link to a location ID, the Help Viewer displays the topic containing the ID and scrolls the window to the ID position.

Examples

If you add an ID to a figure, you must have a caption. The caption is needed in case a cross reference is made to the figure's ID. In that case, the caption becomes a hyperlink to the figure.

Here's the markup for a figure with the ID my-big-picture.

<figure id=my-big-picture entity=big-picture-TIFF>
 Here's My Figure
 <\figure> 

Here's a paragraph where the phrase "easier than ever" has been assigned the ID easy-spot:

Getting help is <location id=easy-spot> easier than ever<\location>.