dthelpgen(1) UNIX System V (1 August 1995) 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:
-generate Specifies that dthelpgen unconditionally
regenerate the browser volume without
first checking if new families or help
volumes are present.
Page 1 (printed 9/3/04)
dthelpgen(1) UNIX System V (1 August 1995) dthelpgen(1)-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
Page 2 (printed 9/3/04)
dthelpgen(1) UNIX System V (1 August 1995) dthelpgen(1)
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:
Page 3 (printed 9/3/04)
dthelpgen(1) UNIX System V (1 August 1995) dthelpgen(1)
/usr/dt/appconfig/help/C/%H.sdl:
/usr/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
Page 4 (printed 9/3/04)
dthelpgen(1) UNIX System V (1 August 1995) dthelpgen(1)
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.
value
Unable to access path -
error status number
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
Page 5 (printed 9/3/04)
dthelpgen(1) UNIX System V (1 August 1995) dthelpgen(1)
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.
error status number value
Unable to access current working directory -
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/.
SEE ALSO
dthelpview(1), dtsearchpath(1), dthffile(4), CDE Help System
Author's and Programmer's Guide.
Page 6 (printed 9/3/04)
