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. 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. 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 for instructions to install a standalone volume on the desktop. 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 . 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. on 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.

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

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 . 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. 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 to review the installation of graphics files. 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. 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. 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. 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. All hyperlinks have been tested. Verify that 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. All graphics are acceptable. Make sure that the graphics have been tested on various color, grayscale, and monochrome displays. 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.sgm file when the DocBook 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, but if you choose not to register a family file, your help volume will not be accessible from the Front Panel Help Viewer. 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. 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. 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 , for additional information about font schemes.