Creating a Topic Hierarchy

The topic hierarchy within your help volume begins with the Part. Each help volume must have one Part. The first level of subtopics below Part must be entered with <Chapter> tags.

Additional levels of subtopics are entered with <Sect1>, <Sect2>, <Sect3>, <Sect4>, and <Sect5>. The DocBook markup language supports five topic levels, but bear in mind that 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>, <Sect1>, <Sect2>, <Sect3>, <Sect4>, or <Sect5> 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.

<Part>
<title>Welcome to ReportMaster</title>
 
<chapter>
        <title>Tutorial for New Users</title>
        overview of chapter topic
        <sect1>
        <title>Module 1: Getting Started</title>
                body of topic
                </sect1>
        <sect1>
        <title>Module 2: Creating Your First Report</title>
                body of topic
                </sect1>
        <sect1>
        <title>Module 3: Printing the Report</title>
                body of topic
                </sect1>
        <sect1>
        <title>Module 4: Saving Your Work and Quitting</title>
                body of topic
                </sect1>
</chapter>
 
<chapter>
        <title>Task Reference</title>
        overview of chapter topic
<sect1>
        <title>Starting and Stopping</title>
        body of topic
        <sect2>
                <title>To Start the Program</title>
                body of topic
                </sect2>
        <sect2>
                <title>To Quit the Program</title>
                body of topic
                </sect2>
<sect1>
        <title>Creating Reports</title>
        body of topic
        <sect2>
                <title>To Create a Detailed Report</title>
                body of topic
                </sect2>
        <sect2>
                <title>To Create a Summary Report</title>
                body of topic
                </sect2>
        </sect1>
</chapter>
 
<chapter>
        <title>Concepts for Advanced Users</title>
        overview of chapter topic
        <sect1>
        <title>Using Report Hot Links</title>
                body of topic
                </sect1>
        <sect1>
        <title>Sharing Reports within a Workgroup</title>
                body of topic
                </sect1>
</chapter>
 
<chapter>
        <title>Reference</title>
        overview of chapter topic
        <sect1>
        <title>Command Summary</title>
                body of topic
                </sect1>
        <sect1>
        <title>Report Attributes Summary</title>
                body of topic
                </sect1>
</chapter>
</part>

(The body of each topic and IDs for the topics are not shown. Spacing and indentations are only for ease of reading, and are not significant.)

To Create a Part

Use the Part element as follows:

<Part>
        <DocInfo>
                <Title>Volume Title</Title>
                <AuthorGroup>
                        <Author>author's name here</Author>
                </AuthorGroup>
                <Abstract>
                        <Para>abstract here</Para>
                </Abstract>
                <LegalNotice>
                        <BlockQuote>
                        <Para>copyrights etc. </Para>
                        </BlockQuote>
                </LegalNotice>
        </DocInfo>
        <Title>Volume Title</Title>
        </PartIntro><Para>This is the home topic.</Para></PartIntro>
        <Chapter Id="chapid">
                <Title>This Chapter</Title>
                <Sect1 Id="sect1id">
                        <Title>Sect1 Heading</Title>
                        <Sect2 Id="sect2id">
                                <Title>Sect2 Heading</Title>
                ...
                ...
                ...
                        </sect2>
                </sect1>
        </chapter>
</Part>

Part may contain the following components in the following order: an optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro, and one or more other book components, like Chapters and Sections.

Note that the Title of the help volume appears twice, if a DocInfo is present: once within DocInfo, and again as the first element following DocInfo.

Example

Here's a sample Part with a PartIntro that includes hyperlinks to the Part's four subtopics:

</Part>
<title>Report Master</title>
<PartIntro>
<Para>Welcome to the online help for Report Master. Please choose one of the following hyperlinks:</Para>
<itemizedlist>
<listitem><para><Link Linkend="Tutorial-id">Tutorial</Link> </para></listitem>
<listitem><para><Link Linkend="Tasks-id">Tasks</Link></para></listitem>
        <listitem><para><Link Linkend="Concepts-id">VolumeDown</Link></para></listitem>
        <listitem><para><Link Linkend="Reference-id">VolumeMute</Link></para></listitem>
</itemizedlist>.
<Para>If you need help, press F1.</Para>
</PartIntro>
...
</Part>

The preceding markup produces this output:

To Add a Topic to the Hierarchy

To add another topic at the same level, close the element using its end tag, then repeat the same element by opening it with its start tag.
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 a <Sect1>, enter a subtopic using <Sect2>.

<sect1>
        <title>Creating Reports</title>
        body of the topic
        <sect2>
                <title>To Create a Detailed Report</title>
                body of the first subtopic
                </sect2>
        <sect2>
                <title>To Create a Summary Report</title>
                body of the second subtopic
                </sect2>
</sect1>

The second Sect2 is also a subtopic of the Sect1.




	NOTE: Sometimes parent-child-sibling metaphors are used to describe the relationships topics in a hierarchy. In the preceding example, the Sect1 topic is the "parent" of both Sect2s (the "children" topics). The two Sect2s are "siblings" of one another. All three topics are "descendents" of the Chapter's topic.

Creating a Topic Hierarchy

Technical documentation

» Table of Contents

» Glossary

» Index

Example

See Also

To Create a Part

Example

To Add a Topic to the Hierarchy

Example