The topic hierarchy within your help volume begins with the home topic. Each help volume must have one home topic. The first level of subtopics below the home topic may be entered with <chapter> or <s1>.
Additional levels of subtopics are entered with <s2>, <s3>, and so on. The HelpTag markup language supports nine topic levels, <s1> to <s9>. However, information more than three or four levels deep often leads many readers to feel lost.
When a help volume is displayed, the help window displays a list of topics in its topic tree. Any topic entered with a <chapter> or <s1...s9> tag automatically appears in the topic tree. This provides an easy way to browse and view topics.
To enable users to display other related information from within a topic, you create hyperlinks. To do so, you assign a unique ID to each destination topic. Hyperlinks make it possible to reference a specific ID anywhere in your help information.
Suppose you want to create a hierarchy to match this simple outline:
Tutorial for New Users Module 1: Getting Started Module 2: Creating Your First Report Module 3: Printing the Report Module 4: Saving Your Work and Quitting Task Reference Starting and Stopping To Start the Program To Quit the Program Creating Reports To Create a Detailed Report To Create a Summary Report Concepts for Advanced Users Using Report Hot Links Sharing Reports within a Workgroup Reference Command Summary Report Attributes Summary
Then the general outline of your help volume would look like this. (The body of each topic and IDs for the topics are not shown.)
<hometopic> Welcome to Report Master <chapter> Tutorial for New Users <s1> Module 1: Getting Started <s1> Module 2: Creating Your First Report <s1> Module 3: Printing the Report <s1> Module 4: Saving Your Work and Quitting <chapter> Task Reference <s1> Starting and Stopping <s2> To Start the Program <s2> To Quit the Program <s1> Creating Reports <s2> To Create a Detailed report <s2> To Create a Summary report <chapter> Concepts for Advanced Users <s1> Using Report Hot Links <s1> Sharing Reports within a Workgroup <chapter> Reference <s1> Command Summary <s1> Report Attributes Summary
Indentation is used here to make it easier to see the structure of the help volume. You do not have to indent your files.
"Accessing Topics" describes assigning IDs to topics
"Creating Hyperlinks" describes how to create hyperlinks
Use the <hometopic> element as follows:
<hometopic> Title Body of topic.
If you include a meta information section (<metainfo>), the home topic must follow it.
Here's a home topic with a title and a single sentence as its body:
<hometopic> Welcome to My Application Congratulations, you've entered the online help for My Application. Here's a sample home topic that includes hyperlinks to its four subtopics: <hometopic> Welcome to Report Master Welcome to the online help for Report Master. Choose one of the following hyperlinks: <list bullet> * <xref Tutorial> * <xref Tasks> * <xref Concepts> * <xref Reference> <\list> If you need help, press F1.
The preceding markup produces this output:
To add another topic at the same level, repeat the same element.
Or, to add a subtopic (a topic one level deeper in the hierarchy), use the element that is one level deeper than the preceding topic.
If the current topic is an <s1>, enter a subtopic using <s2>.
<s1 id=getting-started> Getting Started <s2 id=starting-the-program> Starting the Program Here's the body of the first subtopic. <s2 id=stopping-the-program> Stopping the Program Here's the body of the second subtopic.
The second <s2> is also a subtopic of the <s1>.
Sometimes a parent-child-sibling metaphor is used to describe the relationships between topics in a hierarchy. In the preceding example, the <s1> topic is the "parent" of both <s2>s (the "children" topics). The two <s2>s are "siblings" of one another. All three topics are "descendents" of the home topic.