<!-- $XConsortium: ch06.sgm /main/9 1996/08/26 10:45:30 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. -->
<chapter id="HRDC.CmdS.div.1">
<title id="HRDC.CmdS.mkr.1">Command Summary</title>
<para>This chapter summarizes the command-line options available when the
help commands are run manually in a terminal window.</para>
<sect1 id="HRDC.CmdS.div.2">
<title>Help System Commands</title>
<para>Desktop actions and data types provided by the Help System enable you
to compile and view run-time help files by clicking a help file icon or choosing
a menu item. However, if you want to select particular command options, you
must enter the command manually in a terminal window or create new actions.
</para>
<para>Help actions and data types are defined in two files, <filename>dthelp.dt</filename> and <filename>dtdocbook.dt</filename>, located in the
<filename>/usr/dt/appconfig/types/</filename><symbol role="Variable">lang</symbol> directory.
</para>
<para>The commands summarized here are:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="145*">
<colspec align="left" colwidth="383*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>dtDocBook</command></para></entry>
<entry align="left" valign="top"><para>Compiles DocBook source files into
a run-time file.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>dthelpview</command></para></entry>
<entry align="left" valign="top"><para>Displays a help volume, help topic,
text file, or man page.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>dthelpgen</command></para></entry>
<entry align="left" valign="top"><para>Collects help family files into a new
help volume, <filename>index.hv</filename>, which contains an entry for each
family file.</para></entry></row></tbody></tgroup></informaltable>
</sect1>
<sect1 id="HRDC.CmdS.div.3">
<title id="HRDC.CmdS.mkr.2">Processing DocBook Files (dtdocbook)</title>
<para>The DocBook software, invoked with the <command>dtdocbook</command>command,
compiles your DocBook source files into a run-time help file. You run <command>dtdocbook</command> in the directory where your <symbol role="Variable">volume</symbol><filename>.sgm</filename> source file is located.</para>
<sect2 id="HRDC.CmdS.div.4">
<title>Command Syntax</title>
<programlisting>dtdocbook [command-options] volume</programlisting>
<para>Where <symbol role="Variable">command-options</symbol> are options entered
before the <symbol role="Variable">volume</symbol> name.</para>
</sect2>
<sect2 id="HRDC.CmdS.div.5">
<title>Command Options</title>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="116*">
<colspec align="left" colwidth="412*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>-c</command></para></entry>
<entry align="left" valign="top"><para>Compress an existing SDL file; assume
an input file name extension of &ldquo;<filename>.sdl</filename>&rdquo;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>-d</command></para></entry>
<entry align="left" valign="top"><para>Decompress an existing SDL file; assume
an input file name extension of &ldquo;<filename>.sdl</filename>&rdquo;
</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-h</command></para></entry>
<entry align="left" valign="top"><para>(Help) Emit a synopsis of the <command>dtdocbook</command> command and a list of option to the standard output</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>-l</command></para></entry>
<entry align="left" valign="top"><para>Leave a log file in <filename>basename.log</filename></para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-m</command></para></entry>
<entry align="left" valign="top"><para>(Map) Add additional SDATA and/or character
mapping files</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-o</command> <filename>file</filename></para></entry>
<entry align="left" valign="top"><para>Use <filename>file</filename> as the
output file name; do not add any file name extension</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-r</command></para></entry>
<entry align="left" valign="top"><para>Remove any intermediate files and the
output file; do not complain if none exist</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-u</command></para></entry>
<entry align="left" valign="top"><para>(Uncompressed) Do not compress the
output file during translation</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-v</command></para></entry>
<entry align="left" valign="top"><para>(Verbose) Cause <command>dtdocbook</command> to generate and display parser messages during processing</para></entry>
</row></tbody></tgroup></informaltable>
<para>If the <command>-c</command> option is specified and the file is already
compressed, the file will be decompressed and recompressed. This action is
useful as a means to verify the integrity of a compressed SDL file.</para>
<para>If the <command>-d</command> is specified and the file is already decompressed,
the file will be re-parsed, all precomputations will be performed, and the
file will be re-written. This action is useful as a means to verify the integrity
of an SDL file. It is also useful for forcing a recomputation of the table
of contents, including byte offsets to individual help topics, when such recomputation
is made necessary, for example, by editing the SDL file directly.</para>
<sect3 id="HRDC.CmdS.div.7">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="HeadingAndPage"
linkend="HRDC.CrHV.mkr.2"></para>
</listitem><listitem><para><xref role="HeadingAndPage" linkend="HRDC.Inst.mkr.5">
</para>
</listitem><listitem><para><xref role="HeadingAndPage" linkend="HRDC.CrHV.mkr.6"></para>
</listitem><listitem><para><filename moreinfo="RefEntry">dtdocbook</filename>(1)
man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CmdS.div.8">
<title id="HRDC.CmdS.mkr.4">Displaying Help Topics (dthelpview)</title>
<para>The <command>dthelpview</command> command can be used to display a help
volume, individual help topic, text file, or man page.</para>
<sect2 id="HRDC.CmdS.div.9">
<title>Command Syntax</title>
<para>The various ways to invoke Helpview are:</para>
<itemizedlist><listitem><para><command>dthelpview -helpVolume <symbol role="Variable">volume</symbol> [ -locationId <symbol role="Variable">id</symbol> ]</command>
</para>
</listitem><listitem><para><command>dthelpview -man</command></para>
</listitem><listitem><para><command>dthelpview -manPage</command> <symbol role="Variable">man</symbol></para>
</listitem><listitem><para><command>dthelpview -file</command> <symbol role="Variable">filename</symbol></para>
</listitem></itemizedlist>
<para>Where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="188*">
<colspec align="left" colwidth="340*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>-helpVolume</command> <symbol role="Variable">volume</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the name of the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file you want to view. A path name
is not required unless the volume is not in the current directory <emphasis>and</emphasis> the volume has not been registered.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-locationId</command> <symbol role="Variable">id</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies an ID. <command>dthelpview</command> displays the topic that contains <symbol role="Variable">id</symbol>.
If you do not specify an ID, Helpview uses <filename>_hometopic</filename>
by default.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-man</command></para></entry>
<entry align="left" valign="top"><para>Displays a dialog that prompts for
a man page to view, then displays the requested man page.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-manPage</command> <symbol role="Variable">man</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies that a particular man page
be displayed.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-file</command> <symbol role="Variable">filename</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies that a particular text file
be displayed.</para></entry></row></tbody></tgroup></informaltable>
<para>The default <symbol role="Variable">volume</symbol> and <symbol role="Variable">id</symbol> can be set in <command>dthelpview</command>'s app-defaults file,
<filename>/usr/dt/app-defaults/C/Dthelpview</filename>.</para>
<sect3 id="HRDC.CmdS.div.10">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.Inst.mkr.9">
</para>
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.6"></para>
</listitem><listitem><para><command>dthelpview</command>(1) man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CmdS.div.11">
<title id="HRDC.CmdS.mkr.5">Generating an Index Help Volume (dthelpgen)</title>
<para>The <command>dthelpgen</command> utility creates a special help volume
that enables users to display help volumes registered on their system using
the Front Panel Help Viewer. When a user initially clicks the Help Viewer
control in the Front Panel, <command>dthelpgen</command> is run automatically.
It locates help family files by searching the help search path directories
(local or networked), and then creates an index volume (<filename>index.hv</filename>) in the user's <filename>HomeDirectory/.dt/help/$DTUSERSESSION</filename>directory. Once built, the volume is updated in response to any
of these actions:</para>
<itemizedlist><listitem><para>Add, remove, or modify family files or help
volumes</para>
</listitem><listitem><para>Change the <systemitem class="environvar">LANG</systemitem> environment variable</para>
</listitem><listitem><para>Invoke the <literal>ReloadApps</literal> action
</para>
</listitem><listitem><para>Run <command>dthelpgen</command> manually in a
terminal window</para>
</listitem></itemizedlist>
<para>The index volume is displayed by clicking the Help Viewer control in
the Front Panel. Or, you can manually run <command>dthelpview</command> and
supply the index volume name as shown in this command line:</para>
<programlisting>dthelpview -h index.hv</programlisting>
<sect2 id="HRDC.CmdS.div.12">
<title>Command Syntax</title>
<programlisting>dthelpgen -dir [<symbol role="Variable">options</symbol>]
</programlisting>
<para>Where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="100*">
<colspec align="left" colwidth="356*">
<tbody>
<row>
<entry><para><command>-dir</command></para></entry>
<entry><para>Specifies the directory in which to place the index volume and
intermediate files. This is a required parameter.</para></entry></row></tbody>
</tgroup></informaltable>
</sect2>
<sect2 id="HRDC.CmdS.div.13">
<title>Options</title>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="167*">
<colspec align="left" colwidth="361*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>-generate</command></para></entry>
<entry align="left" valign="top"><para>Specifies that a new index help volume
should be created even if the family files and help volumes on the system
have not been modified.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-file</command> <symbol role="Variable">basename</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the name of the help volume
and any intermediate files generated by <command>dthelpgen</command>. The
default name is <filename>index.hv</filename>.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-lang</command></para></entry>
<entry align="left" valign="top"><para>Specifies which language directories
to search for help families and help volumes. If the <command>-lang</command>
option is set, it takes precedence over the current value of the <systemitem class="environvar">LANG</systemitem> environment variable.</para></entry>
</row></tbody></tgroup><?Pub Caret></informaltable>
<note>
<para>If you run <command>dthelpgen</command> while the index volume is displayed
in a help window, you should close the window, then reopen the index volume.
</para>
</note>
<sect3 id="HRDC.CmdS.div.14">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.Inst.mkr.9"></para>
</listitem><listitem><para><command moreinfo="RefEntry">dthelpgen</command>(1)
man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
