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 hierarchies down to <s9>.
However, information more than three or four levels deep often leads many
readers to feel lost.
Within each topic that has subtopics, you should provide a path for the
reader to get to the subtopics. This requires assigning unique IDs to all
topics and creating hyperlinks within the body of each topic to its
subtopics.
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
How Report Hot Links Work
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> How Report Hot Links Work
<s1> Sharing Reports within a Workgroup
<chapter> Reference
<s1> Command Summary
<s1> Report Attributes Summary
|
You could have created an identical hierarchy by starting with <s1>s in place of the <chapter> tags, <s2>s for the next level, and
<s3>s for the third level. The only difference -- not seen by the
reader -- is the number of files created by HelpTag when you process the
help volume.
Again, 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.
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.
|
To help users who may be new to hyperlinks, you may want to include a
reminder to use F1 to get help on help.
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
The body of this getting started topic should
include a hyperlink to each of the subtopics.
<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>.
Printable version
