<!-- $XConsortium: helpgen.sgm /main/10 1996/09/08 19:52:43 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<RefEntry Id="CDEMX.MAN20.rsml.1">
<RefMeta>
<RefEntryTitle>dthelpgen</RefEntryTitle>
<ManVolNum>user cmd</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Command>dthelpgen</Command></RefName>
<RefPurpose>generates a top-level help browser volume
</RefPurpose>
</RefNameDiv>
<RefSynopsisDiv>
<CmdSynopsis>
<Command>dthelpgen</Command>
<Arg>-dir<Replaceable>directory</Replaceable></Arg>
<Arg Choice="opt"><Replaceable>options</Replaceable></Arg>
</CmdSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para>The
<Command>dthelpgen</Command> 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.
</Para>
<Para>The
<Command>dthelpgen</Command> 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,
<Command>dthelpgen</Command> exits.
If new files are present,
<Command>dthelpgen</Command> posts an information dialog telling the user that it's updating the
browser
volume.
</Para>
<Para>By viewing the
browser
help volume and traversing its
hypertext links, the user can navigate through all of the registered
online help information.
</Para>
<Para>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.
</Para>
<Para>CDE users or system administrators typically do not need
to interact directly with the
<Command>dthelpgen</Command> 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
<Literal>ReloadApps</Literal> Action, or runs
<Command>dthelpgen</Command> directly from a terminal window.
In the first two cases, the resulting
browser
volume is placed in the user's
<Filename>$HOME/.dt/help/$DTUSERSESSION</Filename> directory.
When running
<Command>dthelpgen</Command> from a terminal window, the -dir option must be used to specify
the location to create the resulting
browser
file.
</Para>
</RefSect1>
<RefSect1>
<Title>OPTIONS</Title>
<Para>The following options are available:
</Para>
<VariableList>
<VarListEntry>
<Term><Literal>-generate</Literal></Term>
<ListItem>
<Para>Specifies that
<Command>dthelpgen</Command> unconditionally regenerate the
browser
volume
without first checking if new families or help volumes are present.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>-dir</Literal> <Emphasis>directory</Emphasis></Term>
<ListItem>
<Para>Specifies the directory to deposit the generated files.
The specification can use substitution values.
The <Literal>ENVIRONMENT VARIABLES</Literal>
heading describes the substitution values allowed and their effect.
If the environment variable
<SystemItem Class="EnvironVar">LANG</SystemItem> is not set or is
<SystemItem Class="Constant">NULL</SystemItem>, it is forced to
<Literal>C</Literal>.</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>-file</Literal> <Emphasis>basename</Emphasis></Term>
<ListItem>
<Para>Specifies the base name for the files generated by
<Command>dthelpgen</Command>. The default
name is
browser.
Extensions are appended to
<Emphasis>basename</Emphasis> to create
the file names for the
help
volume.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>-lang</Literal> <Symbol Role="Variable">language</Symbol></Term>
<ListItem>
<Para>Specifies which language directories to search for
help
Family files and
help volumes.
If this option is not set, the default
<SystemItem Class="EnvironVar">LANG</SystemItem> value is used.
If the
<Literal>-lang</Literal> value is set, it takes precedence over the current environment's
<SystemItem Class="EnvironVar">LANG</SystemItem> setting.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>ENVIRONMENT VARIABLES</Title>
<Para>The CDE help system uses two environment variables for locating
help
volumes and Family files within the desktop environment:
</Para>
<VariableList>
<VarListEntry>
<Term><Emphasis>DTHELPSEARCHPATH</Emphasis></Term>
<ListItem>
<Para><Emphasis>System</Emphasis> search path environment variable for locating
help
volumes on local and/or remote nfs mounted systems.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Emphasis>DTHELPUSERSEARCHPATH</Emphasis></Term>
<ListItem>
<Para>Users
search path environment variable for locating user
specific
help
volumes on local and/or remote nfs mounted systems.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
<Para>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.
</Para>
<Para>Field descriptors consist of a percentage (<Literal>%</Literal>) symbol
followed by a single character.
Field descriptors and their substitution values are:
</Para>
<VariableList>
<VarListEntry>
<Term><Literal>%H</Literal></Term>
<ListItem>
<Para>This value is replaced with the current volume or family name being searched
for.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>%L</Literal></Term>
<ListItem>
<Para>Replaced with the current value of the
<SystemItem Class="EnvironVar">LANG</SystemItem> environment variable.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>%%</Literal></Term>
<ListItem>
<Para>Replaced with a single <Literal>%</Literal>.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
<Para>For example, given:
<Literal>DTHELPSEARCHPATH<Literal>="/etc/dt/appconfig/help/%L/%H.sdl"</Literal></Literal></Para>
<Para>The
<Command>dthelpgen</Command> utility looks for files ending with <Filename>.hf</Filename>
in the directory
<Filename>/etc/dt/appconfig/$LANG</Filename>. To find the volumes listed in each <Filename>.hf</Filename>
file,
<Command>dthelpgen</Command> looks in
<Literal>/etc/dt/help/appconfig/$LANG/%H.sdl</Literal> with <Literal>%H</Literal>
replaced with the name of the volume listed in the Family file.
</Para>
<Para>The
<Command>dthelpgen</Command> utility uses both
<Emphasis>DTHELPUSERSEARCHPATH</Emphasis> and
<Emphasis>DTHELPSEARCHPATH</Emphasis>. The default value for
<Emphasis>DTHELPUSERSEARCHPATH</Emphasis> is:
</Para>
<Para><Literal>$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</Literal>
</Para>
<Para>The
<Emphasis>DTHELPUSERSEARCH</Emphasis> is first searched for the requested volume.
If the volume is not found, the
<Emphasis>DTHELPSEARCHPATH</Emphasis> value is searched.
</Para>
<Para>The default value for
<Emphasis>DTHELPSEARCHPATH</Emphasis> path is:
<Literal>/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</Literal></Para>
</RefSect1>
<RefSect1>
<Title>INPUT FILES</Title>
<Para>The following are input files used by
<Command>dthelpgen</Command>.</Para>
<VariableList>
<VarListEntry>
<Term><Literal>&lt;file>.hf</Literal></Term>
<ListItem>
<Para>runtime Help Family file, accessed directly by
<Command>dthelpgen</Command>.</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>&lt;file>.sdl</Literal></Term>
<ListItem>
<Para>runtime Help volume file(s), accessed indirectly through explicit
references within the Help Family file.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>OUTPUT FILES</Title>
<Para>The following are descriptions of the output files generated by
<SystemItem Class="Constant">dthelpgen</SystemItem>.</Para>
<VariableList>
<VarListEntry>
<Term><Literal>browser.hv</Literal></Term>
<ListItem>
<Para>The master runtime browser Help volume file generated by
<Command>dthelpgen</Command>.</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>browser00.ht &amp; browser01.ht</Literal></Term>
<ListItem>
<Para>Runtime browser Help topic files generated by
<Command>dthelpgen</Command>.</Para>
</ListItem>
</VarListEntry>
</VariableList>
<RefSect2>
<Title>Warning Messages</Title>
<VariableList>
<VarListEntry>
<Term><Literal>Zero Volume files found</Literal></Term>
<ListItem>
<Para>Indicates that none of the volumes specified in the Family files are
registered in the system.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Zero Family files found</Literal></Term>
<ListItem>
<Para>Indicates that no Family files are registered in the system.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect2>
<RefSect2>
<Title>Error Messages</Title>
<VariableList>
<VarListEntry>
<Term><Literal>Element of path is not a directory</Literal></Term>
<ListItem>
<Para>Indicates that some part of the path is not a directory.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Access denied for directory path.</Literal></Term>
<ListItem>
<Para>Try running as super user?"
Indicates that some part of path does not allow the caller read,
access or write permission.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Element of path does not exist</Literal></Term>
<ListItem>
<Para>Indicates that some element of path does not exist or is misspelled.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>File system containing path is full</Literal></Term>
<ListItem>
<Para>Indicates that the disc containing the path does not contain any space
or inodes.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Unable to access path - error status number value</Literal></Term>
<ListItem>
<Para>Indicates that there is an access problem of type
<Symbol Role="Variable">value</Symbol> occurred with path.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>File system containing path is read only</Literal></Term>
<ListItem>
<Para>Indicates that the disc containing the path is mounted read-only.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Requires root permission to write to path</Literal></Term>
<ListItem>
<Para>Indicates that some part of the path does not allow the user write
permission.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Write to volume invalid</Literal></Term>
<ListItem>
<Para>Indicates that volume does not have the correct write permissions
for the caller.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Search Path empty</Literal></Term>
<ListItem>
<Para>Indicates that the environment variables.
<Emphasis>DTHELPUSERSEARCHPATH</Emphasis> and/or
<Emphasis>DTHELPSEARCHPATH</Emphasis> were declared but no paths were specified in the variables.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>`title' resource missing</Literal></Term>
<ListItem>
<Para>Indicates that the title resource in a Family file is missing.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>`abstract' resource missing</Literal></Term>
<ListItem>
<Para>Indicates that the abstract resource in a Family file is missing.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>`volumes' resource missing</Literal></Term>
<ListItem>
<Para>Indicates that the volumes resource in a Family file is missing.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>`character' set resource missing</Literal></Term>
<ListItem>
<Para>Indicates that the CharSet resource in a Family file is missing.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Unable to access current working directory - error status number value</Literal></Term>
<ListItem>
<Para>Indicates that the -dir option was specified with a relative path and that
<Command>dthelpgen</Command> is unable to get the current working directory.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Unable to allocate memory</Literal></Term>
<ListItem>
<Para>System resources are used up, no available memory,
<Command>dthelpgen</Command> aborts execution.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Destination directory missing</Literal></Term>
<ListItem>
<Para>Missing
<Emphasis>directory</Emphasis> value for
<Literal>-dir</Literal> option.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>Invalid system language specified</Literal></Term>
<ListItem>
<Para>Non-supported value used with the
<Literal>-lang</Literal> option.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect2>
</RefSect1>
<RefSect1>
<Title>EXAMPLES</Title>
<VariableList>
<VarListEntry>
<Term><Literal>dthelpgen -dir $HOME/.dt/help</Literal></Term>
<ListItem>
<Para>Creates, if required, a new
browser
help volume in the users home directory under <Literal>.dt/help/</Literal>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Literal>dthelpview -dir $HOME/.dt/help -generate</Literal></Term>
<ListItem>
<Para>Forces the creation of a new
browser
help volume and places it in the users home directory under <Literal>.dt/help/</Literal>.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>SEE ALSO</Title>
<Para>&cdeman.dthelpview;, &cdeman.dtsearchpath;, &cdeman.dthffile;, <Emphasis>CDE Help System Author's and Programmer's Guide</Emphasis>.
</Para>
</RefSect1>
</RefEntry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 01:31:55-->
