Creating Run-Time Help Files

When you run HelpTag, it reads your volume.htg or volume.ctg file and any additional source files that are included using entities. Also, graphics file names are validated.

Be sure the /usr/dt/bin/dthelptag command is in your search path. (If you're not sure how to do this, ask your system administrator.)

To Create a Run-Time Help Volume

1. Open File Manager and change to the directory where your volume.htg file is located.

   

2. Select the file icon.

3. Choose Compile from the File Manager Selected menu.

   The volume.htg file is processed and creates a volume.sdl file and volume.err file.

HelpTag Output

The output from HelpTag is a run-time help volume, named volume.sdl. If any errors occurred during processing, they are reported in an error file (volume.err). If no errors were encountered, the volume.err file contains copyright information and several status lines.

Setting the onerror=go option in your helptag.opt file allows the parser to continue processing (if possible) after encountering an error. Without the onerror=go option, the parser halts when the first error is detected. The volume.sdl file is not created until the source file is without errors.

The volume.sdl file, plus your graphics files, are read by the Help System to display help topics. The run-time help file has the same base name as your volume.htg file. For example, if your volume.htg is named Librarian.htg, then the help volume name is Librarian.sdl.

Never rename a run-time help file or graphics file after running HelpTag. The information stored in the volume.sdl file depends on the original names. If you rename your volume.htg file or any of your graphic files, be sure to rerun HelpTag.

To Run the dthelptag Command Manually

Run the dthelptag command as follows:

dthelptag  command-options  volume  parser-options

Where command-options are options entered before the volume name and parser-options are options entered after the volume name. "Processing HelpTag Files (dthelptag)" lists all available options.

Example: Commands

The following command processes a help volume named MyVolume:

dthelptag MyVolume

Using the -verbose option causes the progress of the processing to be displayed on your screen:

dthelptag -verbose MyVolume

Adding a search path enables HelpTag to find files stored in a subdirectory (of the current directory) named graphics:

dthelptag -verbose MyVolume search=graphics

Example: A helptag.opt File

Here's a sample helptag.opt file showing that each option is on a separate line. It would be appropriate for creating a draft version of the volume.

memo
onerror=go 
search=graphics/
search=entityFiles/

Before producing the final version of the help volume, you would remove the memo and onerror=go lines.

See Also

• Chapter 13, Preparing an Installation Package, explains which help files are included in your application installation package.

To Review and Correct Parser Errors

Look at the contents of the volume.err file after running HelpTag (where volume is the base name of your volume.htg file).

Each error listed in the volume.err file begins with a string of asterisks (*****). For example, the following error was detected at line 54 of the file actions:

*****
Line 54 of actions,
Missing end tag for LIST:
...the execution host becomes the current working directory.

<s2 id=EverythingYouNeedToKnow> E...
Current element is LIST begun on Line 28 of actions.

A few lines of the file are shown to give you some context for the error. Also, there is a hint that the current element is a LIST started on line 28 of the same file. An <s2> is not allowed within a list, so it appears that the author forgot to enter the <\list> end tag.

It's possible for a single, simple error to produce several error messages. This is because the first error may cause the parser to lose track of the intended context, making it impossible to interpret subsequent markup properly.

Common Errors

Most processing errors result from these common mistakes:

• Omitting an end tag

• Using an incorrect entity name

• Referring to an invalid element ID

Omitting an end tag for an element is a common mistake. When creating elements, such as a list, figure, note, caution, or warning, be sure to include the end tag. Check your markup carefully especially if you have nested one element within another, such as a figure within a list,

Errors can also be introduced by using an incorrect entity name. In most instances, it is simply a misspelled word. In other cases, an entity name may have been changed, but cross-references to the original name were overlooked. When you change an entity name, remember to search your source file (or files) for all instances of the entity name.

Similarly, changing the ID assigned to an element affects any cross-reference or link to that topic.