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

Chapter 13 Preparing an Installation Package

This chapter identifies the help files that are included in an application installation package. It also describes how help files are handled when your application is registered on the desktop.

Overview

When it comes time to prepare your final product, you must be sure that all your help files are created and installed properly. Your product package includes both the run-time help file (volume.sdl) and its graphic files. Additionally, you can provide a help family file that enables your volume to be viewed using the Front Panel Help Viewer.

Delivering Online Help

Online help can be fully integrated into an application or provided as a standalone help volume. Fully integrated help allows a user to directly access help information from an application by using a Help menu or Help key. A standalone volume on the other hand, can only be displayed using the desktop Help Viewer.

A system administrator may choose to add a standalone help volume to the desktop when an application does not provide integrated help or a customized environment provides a supplemental help volume. See "Standalone Help" for instructions to install a standalone volume on the desktop.

Creating an Installation Package

Your installation package should include these help files:

Run-time help files
Graphics files
Help family file (optional)
Application defaults file (optional)

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

Registering Your Application and Its Help

The desktop's integration utility, dtappintegrate, registers your application and its help files by creating symbolic links between the installed application files and specific desktop directories. Application registration ensures that your help files are located in the directory search paths used by the Help System.

Registration enables two important features of the Help System:

Cross-volume hyperlinks -- A hyperlink in one help volume can refer to another help volume using just the volume name and an ID within the volume. If the destination volume is registered, the link does not have to specify where the volume is stored on the file system.
Help family browsing -- If you also register a "help family", then your help volumes will be browsable using the Help Viewer.

Registering your online help makes it easier to access the help you provide. For authors and programmers, it's easier because references to your volume can use just the volume name -- without specifying the volume's actual location.

If you register a help family with one or more help volumes, you make your help available for general browsing from the Front Panel Help Viewer. This allows access to application-specific help without using the application. Or, if you are writing standalone help, this is the only way for users to get to your help.

Standalone Help

A standalone help volume for an application or a customized environment can be created using the Help System Developer's Kit. To make the help volume accessible from in the desktop browser volume, a system administrator installs the run-time help file, associated graphics, and family file in the /etc/dt/appconfig/help/language directory.

Remember that the run-time help file and its graphics files must be installed in the same relative position as when the help volume was built. See "Graphics Files" to review the installation of graphics files.

What Happens When the Application Is Registered

Application registration creates symbolic links from the run-time help file and family located in app_root/dt/appconfig/help/language to the /etc/dt/appconfig/help/language directory.

Refer to the CDE Advanced User's and System Administrator's Guide for detailed instructions for application registration.

How a Help Volume Is Found

The Help System uses desktop search paths to locate help volumes. When help is requested within an application or a help volume is specified in a command line, the help volume is found by checking a set of search path directories. You can control the directory search path for help volumes by modifying several environment variables. Refer to the CDE Advanced User's and System Administrator's Guide for detailed information about specifying search paths.

Product Preparation Checklists

The following checklists should help you verify that you've prepared your product correctly. Of course, there's no substitute for testing your product by using it as a user will.

For Authors

A final version of the run-time help file was created.

Here are the recommended commands for creating the run-time file:
```
dthelptag -clean volume
 dthelptag volume nomemo onerror=stop
```
The -clean option removes files from any previous dthelptag command, the nomemo option ensures that writer's memos are not displayed, and the onerror=stop option stops processing if any parser errors occur. You should not distribute a help volume that has any parser errors.

All hyperlinks have been tested.

Each hyperlink displays the proper topic or performs the correct action.

Execution aliases have been defined for execution links.

Execution aliases are defined as resources in the application's application defaults file. An execution alias associates a name with a shell command to be executed. If you have used execution links in your help volume, coordinate with the application developer to add these resources to the application defaults file. For more information, refer to "Execution Aliases".

All graphics are acceptable.

The graphics have been tested on various color, grayscale, and monochrome displays.

For Product Integrators

The run-time file is installed.

All graphics are installed in the proper locations.

Each graphics file must be installed in the same relative position to the .sdl file that it was in relative to the.htg file when the HelpTag software was run.

The help volume is registered.

The dtappintegrate script was run to create symbolic links from the installation directory to the registration directory.

A product family file is installed and registered.

The family file is installed with the other help files. When dtappintegrate is run, it creates a symbolic link for the family file. Registering a family file for your help volume is optional. However, if you choose not to register a family file, your help volume will not be accessible from the Front Panel Help Viewer.

For Programmers

The application sets the correct values for these required resources:
```
App-class*helpVolume:        volume
 App-class*helpOnHelpVolume:  help-on-help-volume 
```
The helpVolume resource identifies the help volume for your application.The helpOnHelpVolume identifies the help volume that contains the help on using the help system.

Execution aliases are included in the application defaults file.

An author defines execution aliases as application resources. An execution alias associates a name with a shell command to be executed. If execution links have been used in the help volume, check with the author to identify the resources that need to be added. For more information, refer to "Execution Aliases".

The application sets the desired values for the following optional resources:
```
App-class*DtHelpDialogWidget*onHelpDialog*rows:     rows
 App-class*DtHelpDialogWidget*onHelpDialog*columns:  columns
 App-class*DtHelpDialogWidget*definitionBox*rows:    rows
 App-class*DtHelpDialogWidget*definitionBox*columns: columns 
```
The onHelpDialog resources control the size of the quick help dialogs used to display Help on Help. The definitionBox resources control the size of the quick help dialog used for definition links.

The application uses either the default font resources or defines font resources in the application's application-defaults file.

In most cases an application can rely on the default font resources. However, when custom fonts are used, they must be defined in the application-defaults file. Sample font schemes are provided in the /usr/dt/dthelp/fontschemes directory. See Chapter 14, Native Language Support, for additional information about font schemes.