Table of Contents
dthelpgen -- generates a top-level help browser volume
dthelpgen
[-dirdirectory] [options]
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.
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.
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="/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
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.
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.
- 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.
- 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.
- 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/.
dthelpview(1)
, dtsearchpath(1)
, dthffile(4)
,
CDE Help System Author’s and Programmer’s Guide.
Table of Contents