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

Creating an Installation Package

Your installation package should include these help files:

The run-time help file and any graphics used in the online help are included in your installation package. A help family file is optional for integrated application help. However, if you want your application help to be browsable using the desktop Help Viewer, you must provide a family file. If you are delivering a standalone help volume, you must provide a help family file. See "To Create a Help Family ".

If your application's help volume includes execution links, it is recommended that the author define execution aliases in an application defaults file. This takes advantage of the Help System's default execution policy which will automatically execute links with execution aliases. However, if the help volume is viewed as an independent volume using a separate information viewer, such as the Help Viewer, the Help System will display a confirmation dialog box when an execution link is selected.

Figure 13-1 shows a typical installation package for an application and its help files. Help files are grouped in a separate help subdirectory which contains a default language directory (C is the default). The run-time help file, family file, and graphics files are located in this directory.

Figure 13-1 Application installation package


If your application provides online help in multiple languages, you should create a language subdirectory to accommodate each language (where language matches the user's LANG environment variable). For example, an application that provides both an English and German user interface stores its corresponding online help in two subdirectories: C for English and german for German.

Run-Time Help File

HelpTag creates a single run-time help file, volume.sdl. The base name, volume, is the same as the base name of your volume.htg file. The Help Viewer uses information stored in this master help file and also accesses any associated graphic files.

You don't need to ship the volume.htg or any additional files generated by the HelpTag software.

Graphics Files

If your help volume uses graphics, the image files are typically stored in a separate directory for convenience. However, you may choose to store them in the same location as your volume.htg file.

A run-time help file does not include actual graphic images. Instead, it contains a "reference" to the location of each graphic file. When you run HelpTag, the dthelptag compiler incorporates the relative path names of the graphics files into the help volume.

When the help files are installed, the graphics files must be in the same relative position as when the run-time file was built. Otherwise, the help volume will be unable to locate the graphics files. For example, if your graphics files are in a subdirectory named graphics one level below your volume.htg file, then your installation package must preserve that relative position. The graphics files must be placed in a subdirectory named graphics one level below the volume.sdl file.

Figure 13-2 Relationship of build directories and installation package


Help Family File

You can optionally provide a help family file (volume.hf). A family file briefly describes your help volume and includes copyright information. It can also be used to group one or more related volumes into a single product category.

If you want your help volume to be accessible from the desktop browser volume, then you must provide a family file in your installation package. To create a family file, see "To Create a Help Family ".