Help Volume Components

The Top Level Element: Part

The Part is the top-level element in the structure of a help volume. All other components are subelements of Part in the structural hierarchy.

The structural hierarchy under Part may be several levels deep with Chapters containing Sect1s, Sect1s containing Sect2s, Sect2s containing Sect3s, and so on. To help prevent users from getting lost, however, you should keep your hierarchy as shallow as possible.

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.

Part has the common attributes and a label attribute.

Topics and Subtopics

Topics and subtopics form a hierarchy below the Part. Typically, the first level of topics is divided into chapters, using the Chapter element. Within a chapter, topics are organized into sections, with subtopics of a Sect1 tagged as Sect2s, subtopics of a Sect2 tagged as Sect3s, and so on.

Figure 2-1 “Help volume structural organization” shows a simple hierarchy that includes three chapters. Each chapter contains several first-level sections. The third chapter adds two second-level sections.

Figure 2-1 Help volume structural organization

Part DocInfo Title Chapter Sect1 Sect1 Sect1 Chapter Sect1 Sect2 Sect3 Sect2 Sect1 Sect1 Sect2 Sect2 Sect3

Entities

An author-defined entity can represent a string of characters or a file name. An entity declaration defines the entity name and the string or file it represents.

Entities are useful for:

All entity declarations must be entered before any other markup in your help volume. To include an entity that you have defined, you use an entity reference.

Entity references can be used anywhere within your help volume inside a document type declaration. When you process your help volume with the DocBook software, each entity reference is replaced with the text or file that the entity represents. “Using Entities”describes how to define and use entities.

Meta Information

Meta information is information about your information.

In DocBook markup, meta information about a help volume is contained in the DocInfo element.

DocInfo may contain the following elements in the following order:

The Help System uses the meta information in DocInfo to display the Title of a help volume and its copyright information. The Abstract description is displayed by the desktop Help Viewer in the Front Panel. Other applications capable of displaying help volumes could also make use of this information.

“Creating Meta Information Topics” shows you how to create a meta information section.

Glossary

The glossary includes definitions for important terms that you've used throughout your help volume. If a term is entered using the GlossTerm element, then it automatically becomes a link that, when selected, displays the glossary entry for that term.