dthelpgen(1) USER COMMANDS dthelpgen(1)NAMEdthelpgen - generates a top-level help browser volume
SYNOPSISdthelpgen-dir directory [options]
DESCRIPTION
The dthelpgen utility searches for all TED 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 hyper-
text 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.
TED 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 TED front panel. A browser volume is also gen-
erated 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.
Unix System LaboratoLast change: 1 August 1995 1
dthelpgen(1) USER COMMANDS dthelpgen(1)-dir directory Specifies the directory to deposit the
generated files. The specification can
use substitution values. The ENVIRONMENT
VARIABLES heading describes the substitu-
tion 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 gen-
erated 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 TED help system uses two environment variables for
locating help volumes and Family files within the desktop
environment:
DTHELPSEARCHPATH
System search path environ-
ment variable for locating
help volumes on local
and/or remote nfs mounted
systems.
DTHELPUSERSEARCHPATH
Users search path environ-
ment 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:
Unix System LaboratoLast change: 1 August 1995 2
dthelpgen(1) USER COMMANDS dthelpgen(1)
%H This value is replaced with
the current volume or fam-
ily name being searched
for.
%L Replaced with the current
value of the LANG environ-
ment 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 DTHELPUSER-
SEARCHPATH 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:
Unix System LaboratoLast change: 1 August 1995 3
dthelpgen(1) USER COMMANDS dthelpgen(1)
/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.
<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 dthelp-
gen.
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 direc-
tory.
Access denied for directory path.
Try running as super user?"
Unix System LaboratoLast change: 1 August 1995 4
dthelpgen(1) USER COMMANDS dthelpgen(1)
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.
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 environ-
ment variables. DTHEL-
PUSERSEARCHPATH 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
Unix System LaboratoLast change: 1 August 1995 5
dthelpgen(1) USER COMMANDS dthelpgen(1)
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.
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 direc-
tory.
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.
EXAMPLESdthelpgen-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 ALSOdthelpview(1), dtsearchpath(1), dthffile(4), TED Help System
Author's and Programmer's Guide.
Unix System LaboratoLast change: 1 August 1995 6
