Help Volume Components

A help volume has six major types of components: the home topic, topics, subtopics, entity declarations, meta information, and the glossary.

Home Topic

The home topic is the top-level topic in the topic hierarchy. It is the first topic, or beginning of the help volume. All other topics are subtopics. Your topic hierarchy may be several levels deep. However, to help prevent users from getting lost, you should keep your hierarchy as shallow as possible.

Topics and Subtopics

Topics and subtopics form a hierarchy below the home topic. Typically, the first level of topics following the home topic are divided into chapters, using the <chapter> element. Within a chapter, topics are organized into sections. Subtopics of an <s1> section are entered with <s2>, subtopics of <s2> entered as <s3>, and so on.

Either element, chapter or section, can follow the home topic. There is no visible difference to the user if you start your hierarchy with <chapter> or <s1>. Figure 2-1 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 topic organization

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:

• Referencing a common string of text. This is useful if there is some likelihood that the text may change or you simply don't want to type it repeatedly. Each place you want the text inserted, you reference the entity name.

• Referencing an external file. Entities are required for accessing graphics files. The <figure> and <graphic> elements have a required parameter that specifies an entity name, which refers to a graphic image file.

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. When you process your help volume with the HelpTag 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. It includes information such as the volume's title, copyright notice, and abstract. The abstract is a brief description of the volume's contents.

The Help System uses the meta information 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.

Meta information can also include help topics that are not part of the normal topic hierarchy. Nonhierarchical topics placed in the meta information section are accessed with links.

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

Glossary

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