Chapter 2 Organizing and Writing a Help Volume

Within a help volume, information is organized into five major sections: the home topic, topics and subtopics, entity declarations, meta information, and the glossary.

Home Topic. 

The home topic is the first in the topic hierarchy. 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. The first level of subtopics (following <hometopic>) may begin with <chapter> or <s1>. The <chapter> level is the only level you can skip. That is, subtopics of an <s1> must be entered with <s2>, subtopics of an <s2> must be entered with <s3>, and so on. There is no visible difference to the user if you start your hierarchy with <chapter> or <s1>. The only difference is the number of run-time help files that will be generated (one per chapter).

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. All entity declarations must be entered before any other markup in your help volume. Entity references can be used anywhere within your help volume. When you process your help volume with the HelpTag software (helptag command), each entity reference is replaced with the text or file that the entity represents.

Meta Information.  Meta information is information about your information. It includes information such as the volume's title, copyright notice, and abstract. Meta information also includes general help topics that are not part of the normal topic hierarchy.

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.