Writing Your First Help Volume: A Step-by-Step Example

Create a directory where you will put most of your text files.

Create one or more text files that explain the system you are documenting. For this simple example, all the information is put into a single file named Commands in the directory just created.

	Tip!: If you want to try this example, copy and paste the example text directly from online help into your text editor, instead of typing the text.

Here is what the Commands file contains. The element tags within the angle brackets (< and >) indicate the structure of the information.

   <hometopic> Command Summary

                           <idx|commands|



   Your &product; is capable of the following operations:



   <list bullet>

    <xref ChannelChange>

    <xref VolumeUp>

    <xref VolumeDown>

    <xref VolumeMute>

   <\list>

   

   Choose one of the hyperlinks (underlined phrases)

   to find out how to perform that operation.

   

   <s1 id=ChannelChange> Changing the Channel

                           <idx|channel, changing|

   

   Speak the command:

   

   <ex>channel<\ex>

   

   followed by a number from one to ninety nine.

   

   <s1 id=VolumeUp> Turning Up the Volume

                           <idx|volume, changing|

   

   Speak the command:

   

   <ex>volume up<\ex>

   

   For additional volume, speak the command:

   

   <ex>more<\ex>

   

   (See also <xref VolumeDown>)

   

   <s1 id=VolumeDown>Turning Down the Volume

                           <idx|volume, changing|

   

   Speak the command:



   <ex>volume down<\ex>



   To further reduce the volume, speak the command:



   <ex>more<\ex>



   (See also <xref VolumeUp> and <xref VolumeMute>)





   <s1 id=VolumeMute>Turning Off the Sound

                           <idx|volume, changing|

                           <idx|sound, on/off|



   Speak the command:



   <ex>sound off<\ex>



   To restore the sound, speak the command:



   <ex>sound on<\ex>



   (See also <xref VolumeDown> and <xref VolumeUp>)

Create a text file that gives the information a title, provides copyright information, and provides other information about the online help. In this example, the following text is put into a file called Metainfo in the same directory as the Commands file.

   <metainfo>



        <title>Using the &product;



        <copyright>

        &copy; 1997 Voice Activation Company.  All rights reserved.



        <abstract>Help for Using the &product;.



   <\metainfo>

Create a "build" directory. 

Create a new subdirectory named build/ that is below the directory that contains the Commands and Metainfo files.

Create the master HelpTag file. 

In the build/ subdirectory, create a text file whose name is of the form volume.htg. In this example, the file is named voiceact.htg.

In the .htg file, define entities that associate the names of the Commands and Metainfo files with entity names. Also, define any entities that are used (either directly or indirectly) in the Commands and Metainfo files. Finally, refer to the Commands and Metainfo files by their entity names. In this example, the contents of the voiceact.htg file look like this. The text within the <!-- ... --> elements are comments, which are ignored.

   <!-- Declare an entity for each of the source text files. -->



   <!entity MetaInformation     FILE  "MetaInfo">

   <!entity Commands            FILE  "Commands">





   <!-- Define an entity that names the product and includes

        the trademark symbol (&tm;). -->



   <!entity product "VoAc&tm; Voice-Activated Remote Control">





   <!-- Include the text files. -->



   &MetaInformation;

   &Commands;

Prepare to run HelpTag. 

In the build/ subdirectory, create a file named helptag.opt and put the following text into it. This information selects HelpTag options and indicates where to search for any files defined in FILE entity declarations.

   memo

   onerror=go

   search=./

   search=../

Add the /usr/vhelp/bin/ directory to your PATH environment variable. If you're not sure how to do this, consult the online help or documentation for your operating system or see your system administrator.

Create the run-time help files. 

From the build/ subdirectory, execute the following command:

   helptag -verbose voiceact

This command executes the HelpTag software to create a run-time version of your online help volume. The -verbose option tells HelpTag to display, on your screen, its progress.

If HelpTag reports that errors occurred, fix them by editing or renaming the text files as needed. (If the errors are parser errors, they are listed in a file named voiceact.err.)

Display the help volume. 

From the build/ subdirectory, execute the following command. It displays the new help volume:

   helpview -h voiceact &

You can now scroll the information and jump to related information by choosing hyperlinks.