NAME

dthelpgen — generates a top-level help browser volume

SYNOPSIS

dthelpgen [-dirdirectory] [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:

-generate: Specifies that dthelpgen unconditionally regenerate the browser volume without first checking if new families or help volumes are present.
-dir directory: 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.
-file basename: 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.
-lang language: 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:

DTHELPSEARCHPATH: System search path environment variable for locating help volumes on local and/or remote nfs mounted systems.
DTHELPUSERSEARCHPATH: 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:

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

For example, given: DTHELPSEARCHPATH="/usr/local/dt/etc/appconfig/help/%L/%H.sdl"

The dthelpgen utility looks for files ending with .hf in the directory /usr/local/dt/etc/appconfig/$LANG. To find the volumes listed in each .hf file, dthelpgen looks in /usr/local/dt/etc/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: /usr/local/dt/etc/appconfig/help/%L/%H: /usr/local/dt/etc/appconfig/help/%L/%H.sdl: /usr/local/dt/etc/appconfig/help/%L/%H.hv: /usr/local/dt/etc/appconfig/help/C/%H: /usr/local/dt/etc/appconfig/help/C/%H.sdl: /usr/local/dt/etc/appconfig/help/C/%H.hv: /usr/local/dt/appconfig/help/%L/%H: /usr/local/dt/appconfig/help/%L/%H.sdl: /usr/local/dt/appconfig/help/%L/%H.hv: /usr/local/dt/appconfig/help/C/%H: /usr/local/dt/appconfig/help/C/%H.sdl: /usr/local/dt/appconfig/help/C/%H.hv

INPUT FILES

The following are input files used by dthelpgen.

&<file>.hf: runtime Help Family file, accessed directly by dthelpgen.
&<file>.sdl: 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.

browser.hv: The master runtime browser Help volume file generated by dthelpgen.
browser00.ht && browser01.ht: Runtime browser Help topic files generated by dthelpgen.

Warning Messages

Zero Volume files found: Indicates that none of the volumes specified in the Family files are registered in the system.
Zero Family files found: Indicates that no Family files are registered in the system.

Error Messages

Element of path is not a directory: Indicates that some part of the path is not a directory.
Access denied for directory path.: Try running as super user?" Indicates that some part of path does not allow the caller read, access or write permission.
Element of path does not exist: Indicates that some element of path does not exist or is misspelled.
File system containing path is full: Indicates that the disc containing the path does not contain any space or inodes.
Unable to access path - error status number value: Indicates that there is an access problem of type value occurred with path.
File system containing path is read only: Indicates that the disc containing the path is mounted read-only.
Requires root permission to write to path: Indicates that some part of the path does not allow the user write permission.
Write to volume invalid: Indicates that volume does not have the correct write permissions for the caller.
Search Path empty: Indicates that the environment variables. DTHELPUSERSEARCHPATH and/or DTHELPSEARCHPATH were declared but no paths were specified in the variables.
`title' resource missing: Indicates that the title resource in a Family file is missing.
`abstract' resource missing: Indicates that the abstract resource in a Family file is missing.
`volumes' resource missing: Indicates that the volumes resource in a Family file is missing.
`character' set resource missing: Indicates that the CharSet resource in a Family file is missing.
Unable to access current working directory - error status number value: Indicates that the -dir option was specified with a relative path and that dthelpgen is unable to get the current working directory.
Unable to allocate memory: System resources are used up, no available memory, dthelpgen aborts execution.
Destination directory missing: Missing directory value for -dir option.
Invalid system language specified: Non-supported value used with the -lang option.

EXAMPLES

dthelpgen -dir $HOME/.dt/help: Creates, if required, a new browser help volume in the users home directory under .dt/help/.
dthelpview -dir $HOME/.dt/help -generate: Forces the creation of a new browser help volume and places it in the users home directory under .dt/help/.