dthelpgen(1)

NAME
dthelpgen - generates a top-level help browser volume

SYNOPSIS
dthelpgen -dir directory [options]

DESCRIPTION
The dthelpgen utility searches for all CDE help family files installed and registered, and generates a help volume named browser, which contains hypertext links to all help families and volumes found. By default, the scope of this search includes only the local system; however, it can be extended to remote systems using the environment variables described below.

The dthelpgen utility only updates the browser help volume if new family files or volumes are detected within the search path directories. In the case where no new family files are present, dthelpgen exits. If new files are present, dthelpgen posts an information dialog telling the user that it's updating the browser volume.

By viewing the browser help volume and traversing its hypertext links, the user can navigate through all of the registered online help information.

To view the browser volume, select the Help Viewer control from the desktop's Front Panel. The top level of the browser volume lists product families. The second level, under each family, lists the volumes that are members of the product family.

CDE users or system administrators typically do not need to interact directly with the dthelpgen utility. A browser volume is generated (when one does not already exist, or is out of date) when the user selects the Help Viewer control from the CDE front panel. A browser volume is also generated when the user executes the ReloadApps Action, or runs dthelpgen directly from a terminal window. In the first two cases, the resulting browser volume is placed in the user's $HOME/.dt/help/$DTUSERSESSION directory. When running dthelpgen from a terminal window, the -dir option must be used to specify the location to create the resulting browser file.

OPTIONS
The following options are available:

    Specifies that dthelpgen unconditionally regenerate the browser volume without first checking if new families or help volumes are present. Specifies the directory to deposit the generated files. The specification can use substitution values. The ENVIRONMENT VARIABLES heading describes the substitution values allowed and their effect. If the environment variable LANG is not set or is NULL, it is forced to C. Specifies the base name for the files generated by dthelpgen. The default name is browser. Extensions are appended to basename to create the file names for the help volume. Specifies which language directories to search for help Family files and help volumes. If this option is not set, the default LANG value is used. If the -lang value is set, it takes precedence over the current environment's LANG setting.

ENVIRONMENT VARIABLES
The CDE help system uses two environment variables for locating help volumes and Family files within the desktop environment:

    System search path environment variable for locating help volumes on local and/or remote nfs mounted systems. Users search path environment variable for locating user specific help volumes on local and/or remote nfs mounted systems.

The environment variables contain colon-separated lists of directory paths. Each directory path can contain both environment variable names as well as special field descriptors that are expanded at runtime. Field descriptors consist of a percentage (%) symbol followed by a single character. Field descriptors and their substitution values are:

    This value is replaced with the current volume or family name being searched for. Replaced with the current value of the LANG environment variable. Replaced with a single %.

For example, given:
DTHELPSEARCHPATH="/etc/dt/appconfig/help/%L/%H.sdl" The dthelpgen utility looks for files ending with .hf in the directory /etc/dt/appconfig/$LANG. To find the volumes listed in each .hf file, dthelpgen looks in /etc/dt/help/appconfig/$LANG/%H.sdl with %H replaced with the name of the volume listed in the Family file. The dthelpgen utility uses both DTHELPUSERSEARCHPATH and DTHELPSEARCHPATH. The default value for DTHELPUSERSEARCHPATH is:
$HOME/.dt/help/$DTUSERSESSION/%H:
$HOME/.dt/help/$DTUSERSESSION/%H.sdl:
$HOME/.dt/help/$DTUSERSESSION/%H.hv:
$HOME/.dt/help/%H:
$HOME/.dt/help/%H.sdl:
$HOME/.dt/help/%H.hv The DTHELPUSERSEARCH is first searched for the requested volume. If the volume is not found, the DTHELPSEARCHPATH value is searched. The default value for DTHELPSEARCHPATH path is:
/etc/dt/appconfig/help/%L/%H:
/etc/dt/appconfig/help/%L/%H.sdl:
/etc/dt/appconfig/help/%L/%H.hv:
/etc/dt/appconfig/help/C/%H:
/etc/dt/appconfig/help/C/%H.sdl:
/etc/dt/appconfig/help/C/%H.hv:
/usr/dt/appconfig/help/%L/%H:
/usr/dt/appconfig/help/%L/%H.sdl:
/usr/dt/appconfig/help/%L/%H.hv:
/usr/dt/appconfig/help/C/%H:
/usr/dt/appconfig/help/C/%H.sdl:
/usr/dt/appconfig/help/C/%H.hv

INPUT FILES
The following are input files used by dthelpgen.

    runtime Help Family file, accessed directly by dthelpgen. runtime Help volume file(s), accessed indirectly through explicit references within the Help Family file.

OUTPUT FILES
The following are descriptions of the output files generated by dthelpgen.

    The master runtime browser Help volume file generated by dthelpgen. Runtime browser Help topic files generated by dthelpgen.

  Warning Messages

    Indicates that none of the volumes specified in the Family files are registered in the system. Indicates that no Family files are registered in the system.

  Error Messages

    Indicates that some part of the path is not a directory. Try running as super user?" Indicates that some part of path does not allow the caller read, access or write permission. Indicates that some element of path does not exist or is misspelled. Indicates that the disc containing the path does not contain any space or inodes. Indicates that there is an access problem of type value occurred with path. Indicates that the disc containing the path is mounted read-only. Indicates that some part of the path does not allow the user write permission. Indicates that volume does not have the correct write permissions for the caller. Indicates that the environment variables. DTHELPUSERSEARCHPATH and/or DTHELPSEARCHPATH were declared but no paths were specified in the variables. Indicates that the title resource in a Family file is missing. Indicates that the abstract resource in a Family file is missing. Indicates that the volumes resource in a Family file is missing. Indicates that the CharSet resource in a Family file is missing. Indicates that the -dir option was specified with a relative path and that dthelpgen is unable to get the current working directory. System resources are used up, no available memory, dthelpgen aborts execution. Missing directory value for -dir option. Non-supported value used with the -lang option.

EXAMPLES

    Creates, if required, a new browser help volume in the users home directory under .dt/help/. Forces the creation of a new browser help volume and places it in the users home directory under .dt/help/.

SEE ALSO
dthelpview(1), dtsearchpath(1), dthffile(4), CDE Help System Author's and Programmer's Guide.