 |
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]
OPTIONS
The following options are available:
-generate
Specifies that dthelpgen unconditionally regenerates 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.
DESCRIPTION
The dthelpgen utility searches for all CDE help family files installed and
registered. It then 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.
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:
<filename>/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</filename>
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
user's home directory under .dt/help/.
INPUT FILES
The following input files are 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.
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 |
|