 |
Index for
Section 1 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dthelpgen(1)
CDE
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.
-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="/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.
<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/.
SEE ALSO
dthelpview(1), dtsearchpath(1), dthffile(4), CDE Help System Author's and
Programmer's Guide.
|
Index for
Section 1 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|