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

Adding Your Help to the Browser Volume

The desktop provides a special help volume called the browser volume that lists help volumes available on your system. The browser volume is displayed by clicking the Help Viewer control in the Front Panel.

You can view assorted help volumes directly from the browser volume. This allows access to application-specific help without starting the application. Or, if you are writing standalone help, this is the only way for users to get to your help.

Figure 4-1 Browser help volume displaying help families

To make your help volume available in the browser volume, you create a help family file. When your application is registered on the desktop, the presence of a family file causes the help volume to be included in the browser volume.

Browser Volume

A desktop utility creates and updates the browser volume. When a user clicks on the Front Panel Help Viewer for the first time, the utility is automatically run. It identifies help volumes and help family files that are located in the help search path directories. It creates a file called browser.hv in the user's HomeDirectory/.dt/help/$DTUSERSESSION directory. After initial creation, the volume is updated only if changes have occurred.

To manually update the browser volume, refer to "Generating a Browser Help Volume (dthelpgen)".

Any help volume listed in the browser volume can be viewed by selecting the volume title. Because you can display and navigate through different volumes, the browser help window includes an additional button, called Top Level. You can use this button to return to the browser list after displaying one or more volumes.

Help Family File

The desktop utility examines help family files to identify which help volumes are gathered into the browser volume. Figure 4-1 shows two help families, Common Desktop Environment and Overview and Basic Desktop Skills, listed in the browser volume. Each family file consists of one or more related help volumes. For example, the Common Desktop Environment family includes different volumes that describe the desktop.

Refer to the CDE Advanced User's and System Administrator's Guide for a detailed explanation of how an application and its help files are installed on the desktop.

To Create a Help Family

Pick a file name that is unique to your product. Use the.hf extension to identify the file as a help family.
```
 
family.hf 
```

Enter the following lines into the file:
```
*.charSet:      character-set
 *.title:        family title
 *.bitmap:       icon file
 *.abstract:     family abstract
 *.volumes:      volume volume volume ... 
```
Where character-set specifies the character set used by the family title and family abstract strings. See "Understanding Font Schemes" for a list of supported character sets. The family title and family abstract should not contain any HelpTag markup; this file is not processed with the HelpTag software.

The icon file is optional. If you provide one, the path you use to specify the location of the file should be a complete path name. If you do not provide an icon, do not include the *.bitmap resource in your family file.

The list of volume names identifies which volumes belong to the family. The volumes will be listed in the order they appear on this line. A volume may be listed in more than one family.

If any of the values occupy more than one line, end each line -- except the last -- with a backslash (\).

Any line in the file that begins with an ! (exclamation mark) is a comment line and is ignored.

When you prepare your final product, you should install your family.hf file with the rest of your help files. When the desktop integration script, (dtappintegrate) is run, it creates the symbolic links to your family file.

The CDE Advanced User's and System Administrator's Guide describes how to run the dtappintegrate script.

Example

Here's a family file for the desktop's online help. Comments at the top of the file identify the family and release version.

!##############################################
 !#                                            #
 !#          Desktop  Help Family              #
 !#                                            #
 !#                 Version 1.0                #
 !#                                            #
 !##############################################
 *.charSet:      ISO-8859-1
 *.title:        Desktop Version 1.0
 *.bitmap:       /usr/dt/appconfig/help/C/cdelogo.pm
 *.abstract:     Overview and Basic Desktop Skills \ 
                 * File Manager and the Desktop \ 
                 * Front Panel \ 
                 * Application Manager \ 
                 * Style Manager \ 
                 * Text Editor \ 
                 * Mailer
 
*.volumes: Intromgr.sdl Filemgr.sdl FPanel.sdl
            Appmanager.sdl Stylemgr.sdl
            Textedit.sdl Mailer.sdl

The help family file actually included with the desktop software may not exactly match this example.

To Display the Browser Volume

Choose the Help Viewer control from the desktop's Front Panel.

Scroll the help window to view the help families available on your system.

If desired, display a volume by selecting the help family title.

Note -
To view help information about the Help System, choose the title Common Desktop Environment and then Desktop Help System.

To Display the browser Volume Manually

Run the dthelpview command as follows:

dthelpview -helpVolume browser