helpgen(1)

NAME

helpgen − the help file generation utility

SYNOPSIS

helpgen [−dir directory] [−file basename]

DESCRIPTION

helpgen provides a method of collecting and accessing families of Help Topics. The help topics must have been generated using the helptag(1) software and placed in family files by a user. Use helpview(1) to view the resulting browser help volume.

OPTIONS

−dir directory
Specifies the directory to deposit the generated files. The specification can use substitution values. The Environment Variables section describes the substitution values allowed and their affect. If the environment variable LANG is not set or null, it is forced to C. The default directory is /usr/vue/help/%L/Browser.

−file basename
Specifies the base file name. The default name is browser. Extensions are appended to basename to create the file names for the help volume and topic files.

THE FAMILY FILE

A user collects/organizes Help volumes into one or more Help Family files. These famliy files describe which help volumes are related to each other and why the volumes are related to each other. The relationship can be arbitrary (I.E. "The files are used often") but most often are logical (I.E. "System Administration Information").

The Family file is based on the X11 syntax for application resources. It contains a character set, title, abstract, volume list and an optional image name.

FAMILY FILE FIELDS

charSet Specifies the character set (font set) to use when parsing/reading the title and abstract. The default is ’iso8859-1’.

title Specifies the title of the family.

abstract
Specifies the abstract for the family. Used to describe the family, it gives information about what type of volumes are in this family or why these volumes are related. For long abstracts, the backslash character can be used to continue to the next line.

volumes
Specifies the volumes contained in the family. This is a list of volume names seperated by spaces. The ending .hv extension must be specified if the search path contains a %H rather than a %H.hv. See the Environment Variables section for more information about the search path.

bitmap Specifies the image that pictorally describes the family. The extension to the file name indicates the image type.
.xwd     X11 XWD file
.tif     TIFF 5.0 image file
.pm      X11 X Pixmap file
.bm      X11 Bitmap file

FAMILY FILE EXAMPLE

        ∗.charSet:    iso8859-1

        ∗.title:      Developer’s Information About The Help System

        ∗.abstract:   Help for an application requires The HP Help \
        Developer’s Kit and ...... A demo help document provides \
        examples of writing style, hypertext links and .....

        ∗.volumes:    developers helpdemo.hv
        ∗.bitmap:     /usr/local/bitmap/smiley.bm

EXTERNAL INFLUENCES

Environment Variables

XVHHELPUSERSEARCHPATH and XVHHELPSYSTEMSEARCHPATH contain colon-seperated lists of pseudo-pathnames. Each pseudo-pathname contains a name template. The name template consists of an optional path prefix, one or more substitution file descriptors and an optional file name suffix.

Field descriptors consist of a % followed by a single character. Field descriptors and their substitution values are:

%H Ignored when searching for family files. Replaced with the name of the volume file desired when finding volumes contained in a family.

%L Replaced with the value of LANG.

%T Replaced with family or volumes depending on whether a family file or volume is being looked for.

%% Replaced with a single %.

For example, given:

XVHHELPSYSTEMSEARCHPATH="/usr/vhelp/%T/%L/%H.hv"

helpgen looks for files ending with .hf in the directory /usr/vhelp/family/$LANG. To find the volumes listed in each .hf file, helpgen looks in /usr/vhelp/volumes/$LANG/%H.hv with %H replaced with the name of the volume listed in the family file.

helpgen uses both XVHHELPUSERSEARCHPATH and XVHHELPSYSTEMSEARCHPATH. If XVHHELPUSERSEARCHPATH is null, not set or does not contain any family files, XVHHELPSYSTEMSEARCHPATH is searched. If XVHHELPSYSTEMSEARCHPATH is null or not set, helpgen uses the default paths:
        /usr/vhelp/%T/%L/%H
        /usr/vhelp/%T/%H
        /usr/vhelp/%T/%L/%H.hv
        /usr/vhelp/%T/%H.hv
        /usr/vhelp/%T/C/%H
        /usr/vhelp/%T/C/%H.hv

VUE 3.0

Changing XVHHELPSYSTEMSEARCHPATH

If the XVHHELPSYSTEMSEARCHPATH variable is changed, it is recommended that it is modified in the /usr/vue/config/Xsession script. This ensures the same search path for all TriTeal VUE 3.0 users, since /usr/vue/config/Xsession is executed every time a user logs in to a TriTeal VUE 3.0 session.

Example: Accessing Remote Systems

To access the Help Files on a remote system, the system administrator will

1 On the remote system, export the disks containing the help files. Also, export the disk containing the /usr/vhelp directory.

2 On the local system, mount the disks from the remote system. It strongly recommended to mount the disks under the /nfs/<hostname> directory. I.E.
/nfs/<hostname>/usr/vhelp
/nfs/<hostname>/<help files directory>

3 Modify the Xsession script by adding the following lines (replacing the <hostname> with the name of the remote system). Be sure to include a backslash at the end of each line but the last line:
XVHHELPSYSTEMSEARCHPATH=\
        /usr/vhelp/%T/%L/%H: \
        /usr/vhelp/%T/%H: \
        /usr/vhelp/%T/%L/%H.hv: \
        /usr/vhelp/%T/%H.hv: \
        /usr/vhelp/%T/C/%H: \
        /usr/vhelp/%T/C/%H.hv: \
        /nfs/<hostname>/usr/vhelp/%T/%L/%H: \
        /nfs/<hostname>/usr/vhelp/%T/%H: \
        /nfs/<hostname>/usr/vhelp/%T/%L/%H.hv: \
        /nfs/<hostname>/usr/vhelp/%T/%H.hv: \
        /nfs/<hostname>/usr/vhelp/%T/C/%H: \
        /nfs/<hostname>/usr/vhelp/%T/C/%H.hv

Creating the Browser

Some software packages automatically run helpgen (via the customize and decustomize scripts) when the software is installed or removed. If XVHHELPSYSTEMSEARCHPATH has been modified in the Xsession file, helpgen will use this modified value only if run during a TriTeal VUE 3.0 session. To ensure that helpgen uses the correct search path:

Update the software while logged into a TriTeal VUE 3.0 session.

Or after installing or removing any software containing help files, log into a TriTeal VUE 3.0 session and manually run /usr/vue/bin/helpgen.

COPYRIGHT

ORIGIN

Hewlett-Packard Company

Museum

Related Articles