Creating a Topic Hierarchy

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.

Example

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.

See Also

• "Accessing Topics" describes assigning IDs to topics

• "Creating Hyperlinks" describes how to create hyperlinks

To Create a Home Topic

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.

Examples

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 a Topic to the Hierarchy

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.

Example

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.