487 lines
14 KiB
Plaintext
487 lines
14 KiB
Plaintext
<!-- $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><file>.hf</Literal></Term>
|
|
<ListItem>
|
|
<Para>runtime Help Family file, accessed directly by
|
|
<Command>dthelpgen</Command>.</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term><Literal><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 & 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-->
|