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

HRDC.Inst.mkr.4
HRDC.Inst.mkr.5
HRDC.Inst.mkr.9
HRDC.Inst.mkr.12

## 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 HRDC.Inst.mkr.10 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 HRDC.CrHV.mkr.11.

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.

HRDC.Inst.mkr.6 on HRDC.Inst.mkr.6 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.

### 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

DocBook creates a single run-time help file, volume`.sdl`. The base name, volume, is the same as the base name of your volume`.sgm` 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`.sgm` or any additional files generated by the DocBook 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 `.sgm` 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 DocBook, the `dtdocbook` 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`.sgm` 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.

#### 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 HRDC.CrHV.mkr.11.

## 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. 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 index 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 HRDC.Inst.mkr.7 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 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 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 would.

### For Authors

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

   Here are the recommended commands for creating the run-time file:

   `dtdocbook -r` volume

   `dtdocbook` volume

   The `-r` option removes files from any previous `dtdocbook` command. You should not distribute a help volume that has any parser errors. If any parser errors have occurred, dtdocbook will place them in the intermediate file volume`.log`.

2. All hyperlinks have been tested.

   Verify that each hyperlink displays the proper topic or performs the correct action.

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

4. All graphics are acceptable.

   Make sure that the graphics have been tested on various color, grayscale, and monochrome displays.

### For Product Integrators

1. The run-time file is installed.

2. 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`.sgm` file when the DocBook software was run.

3. The help volume is registered.

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

4. 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, but if you choose not to register a family file, your help volume will not be accessible from the Front Panel Help Viewer.

### For Programmers

1. 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` resource identifies the help volume that contains the help on using the help system.

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

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

4. 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 HRDC.Lang.mkr.1, for additional information about font schemes.