Common Desktop Environment: Help System Author's and Programmer's Guide

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

Typically you organize your help files in a help directory. This step-by-step example demonstrates how to create and view a standalone help volume. (As a standalone volume, it does not involve interaction with an application.)

To create and process a help volume, you follow these steps:

Create the source directory for help files.

Create the build directory.

Create the master HelpTag file.

Create the helptag.opt file.

Create the run-time help files.

Display the help volume.

Each task is described in the section that follows. The markup language used in the text files is introduced later in this chapter. HelpTag markup is described more fully in Chapter 3, Writing a Help Topic and Chapter 5, HelpTag Markup Reference.

Create the Source Directory

Create a directory named helpfiles where you will create and process your help files.

Create a text file named Commands in the directory just created.

For this example, all the information is put into a single file. Typically, you will use multiple files to fully explain the system or application you are writing help for.

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

Type the following markup text in the Commands file.

  <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; 1995 Voice Activation Company.  All rights reserved.
      <abstract> Help for Using the &product;.
 <\metainfo> 
```

Create the Build Directory

Create a subdirectory named build in the helpfiles directory.

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.
```

<!entity MetaInformation     FILE   "Metainfo">
 <!entity Commands            FILE   "Commands">

 

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

 

 &MetaInformation;
 &Commands;
```

Create the helptag.opt File

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.
```
onerror=go
 memo
 search=./
 search=../
```
The onerror=go option instructs the HelpTag software to continue processing input files even if an error occurred. See "Parser Options" for an explanation of parser options. For a complete list and description of parser options, refer to the dthelptag(1) man page.

Verify that the /usr/dt/bin directory is in your search path by typing this command in a terminal window:
```
echo $PATH
```
If the directory is not in your path, add it to your PATH environment variable. If you're not sure how to do this, refer to your system documentation or ask your system administrator.

Create the Run-Time Help Files

Open File Manager and change to the build subdirectory. Select the voiceact.htg file icon and choose Compile from the Selected menu in File Manager.

This executes the HelpTag software which creates a run-time version of your online help volume (voiceact.sdl). Status and error messages are placed in a new file, whose name is of the form volume.err.

Open the voiceact.err file to check that your file processed without errors. If errors occurred, fix them by editing or renaming the text files as needed.

Note -
You can run HelpTag manually in a terminal window.

To do so, execute the following command:
```
dthelptag -verbose voiceact.htg
```
The -verbose option tells HelpTag to display its progress on your screen.

Display the Help Volume

From the build subdirectory, double-click the voiceact.sdl file icon.

This displays the help volume using the desktop Help Viewer. You can now scroll the information and jump to related information by choosing hyperlinks.

Note -

You can run the Help Viewer manually in a terminal window.

To do so, execute the following command. It displays the new help volume.

dthelpview -h voiceact.sdl