253 lines
9.7 KiB
Plaintext
253 lines
9.7 KiB
Plaintext
<!-- $XConsortium: docbook.sgm /main/7 1996/10/22 12:17:02 rws $ -->
|
|
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1996 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1996 Novell, Inc. -->
|
|
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1996 Hitachi. -->
|
|
<![ %CDE.C.CDE; [<refentry id="cde.INFO.dtdocbook">]]>
|
|
<refmeta><refentrytitle>dtdocbook</refentrytitle><manvolnum>user cmd</manvolnum>
|
|
</refmeta>
|
|
<refnamediv><refname><command>dtdocbook</command></refname><refpurpose>DocBook
|
|
to SDL translator</refpurpose></refnamediv>
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>dtdocbook</command><arg choice="opt">−c</arg><arg choice="opt">−d</arg><arg choice="opt">−h</arg><arg choice="opt">−m</arg>
|
|
<arg choice="opt">−o <replaceable>file</replaceable></arg><arg choice="opt">−r</arg><arg choice="opt">−s <replaceable>dir</replaceable></arg>
|
|
<arg choice="opt">−u</arg><arg choice="opt">−v</arg><arg choice="opt">−x</arg><arg><replaceable>file</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1>
|
|
<title>DESCRIPTION</title>
|
|
<para>The <command>dtdocbook</command> command converts documents that conform
|
|
to the DocBook 2.2.1 DTD (Document Type Definition) subelement PART to documents
|
|
that conform to the SDL 1.2 DTD. The reason for translating DocBook documents
|
|
to SDL is to make them readable by the the DtHelp viewer.</para>
|
|
<para>The CDE documentation authoring environment produces documents that
|
|
conform to the DocBook DTD Version 2.2.1. The CDE online documentation browser
|
|
(<command>dtinfo</command>) accepts only documents in the DocBook DTD 2.2.1
|
|
format. The CDE online help viewer (<command>DtHelp</command>) accepts only
|
|
documents in the SDL DTD Version 1.2 format. Both DocBook and SDL are implementations
|
|
of the SGML standard, ISO 8879:1986. <command>dtdocbook</command> translates
|
|
document from one format to the other, making them suitable for use with
|
|
the help viewer.</para>
|
|
<para>During translation, several items are precomputed to accelerate run-time
|
|
display of the resulting SDL document. These items include: the table of
|
|
contents, the keyword index, cross-reference resolution, and the labeling
|
|
of ordered lists. By default, <command>dtdocbook</command> also compresses
|
|
the SDL document.</para>
|
|
<para><command>dtdocbook</command> requires only the filename of the input
|
|
file. Note that the input file can be either a DocBook document or an SDL
|
|
document, depending on the operation you want <command>dtdocbook</command>
|
|
to perform. If the file name ends in the characters <filename>.sgm</filename>
|
|
or <filename>.sdl</filename>, <command>dtdocbook</command> assumes they are
|
|
the file name extension removes them to create the base name for all intermediate
|
|
files and for the final output file. If the file name does not end in the
|
|
characters <filename>.sgm</filename> or <filename>.sdl</filename>, <command>dtdocbook</command> uses the file name as given for the base name. If you
|
|
request either compression or decompression (<literal>−c</literal>
|
|
or <literal>−d</literal> option) of an existing SDL file, the input
|
|
file name extension will be <filename>.sdl</filename>. If you specify neither <literal>−c</literal> nor <literal>−d</literal>, the input file name extension
|
|
must be <filename>.sgm</filename>. The output file name extension will always
|
|
be <filename>.sdl</filename> unless you specify the <literal>−o</literal>
|
|
option, in which case <command>dtdocbook</command> will use the output filename
|
|
that you specify.</para>
|
|
<para>If you specify the <literal>−c</literal> option and the file is
|
|
already compressed, <command>dtdocbook</command> will decompress and recompress
|
|
the file. This is a convenient way to verify the integrity of a compressed
|
|
SDL file.</para>
|
|
<para>If you specify the <literal>−c</literal>
|
|
option and the file is already decompressed,
|
|
<command>dtdocbook</command> will re-parse the file,
|
|
repeat all precomputations, and
|
|
update the existing file. This is a convenient way
|
|
to verify the integrity of an SDL
|
|
file. It also allows you to force a recomputation
|
|
of the table of contents to reflect edits
|
|
made to the SDL file. You must recompute the table
|
|
of contents because it consists
|
|
of byte offsets to the individual help topics in the
|
|
file.</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>OPTIONS</title>
|
|
<para>The following options are available:</para>
|
|
<variablelist>
|
|
<varlistentry><term><literal>−c</literal></term>
|
|
<listitem>
|
|
<para>Compresses an existing SDL file. This option
|
|
assumes an
|
|
input file name extension of <filename>.sdl</filename>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−d</literal></term>
|
|
<listitem>
|
|
<para>Decompresses an existing SDL file. This option
|
|
assumes an
|
|
input file name extension of <filename>.sdl</filename>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−h</literal></term>
|
|
<listitem>
|
|
<para>Outputs a summary of the command and its options
|
|
to standard output.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−m</literal></term>
|
|
<listitem>
|
|
<para>Adds additional SDATA and/or character mapping
|
|
files.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−o</literal> <emphasis>file</emphasis></term>
|
|
<listitem>
|
|
<para>Uses the specified filename for the output file
|
|
and does not add any file name extension.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−r</literal></term>
|
|
<listitem>
|
|
<para>Removes any intermediate files and the output
|
|
file. If none exist,
|
|
<command>dtdocbook</command> does not issue an error
|
|
message.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−s</literal> <emphasis>dir</emphasis></term>
|
|
<listitem>
|
|
<para>Instructs <command>dtdocbook</command> to find the DocBook SGML declaration
|
|
and associated files in the specified directory.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−u</literal></term>
|
|
<listitem>
|
|
<para>Turns off compression for the output file during translation.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−v</literal></term>
|
|
<listitem>
|
|
<para>Instructs <command>dtdocbook</command> to generate and display parser
|
|
messages during processing (verbose mode).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><literal>−x</literal></term>
|
|
<listitem>
|
|
<para>Retains intermediate files when finished. This option is used primarily
|
|
for debugging <command>dtdocbook</command> itself.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>OPERANDS</title>
|
|
<para>The following operand is supported:</para>
|
|
<variablelist>
|
|
<varlistentry><term><symbol role="Variable">file</symbol></term>
|
|
<listitem>
|
|
<para>The document file to be input to <command>dtdocbook</command>. The
|
|
file can be in either DocBook or SDL format, depending on which options you
|
|
specify.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>EXIT STATUS</title>
|
|
<variablelist remap="tight">
|
|
<varlistentry><term>0</term>
|
|
<listitem>
|
|
<para>The input file was processed successfully.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term>><?Pub Caret>1</term>
|
|
<listitem>
|
|
<para>The operation failed.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>ENVIRONMENT VARIABLES</title>
|
|
<para><command>dtdocbook</command> references the <systemitem class="environvar">LANG</systemitem> variable to determine the language used for the input file's
|
|
contents. <systemitem class="environvar">LANG</systemitem> can be overridden
|
|
by the <Symbol>LANG</Symbol> attribute of the DocBook PART element.</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>RESOURCES</title>
|
|
<para>None.</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>ACTIONS/MESSAGES</title>
|
|
<para>None.</para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>ERRORS/WARNINGS</title>
|
|
<para><literal>TO BE SUPPLIED</literal></para>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>FILES</title>
|
|
<variablelist>
|
|
<varlistentry><term><emphasis>file</emphasis>.sgm</term>
|
|
<listitem>
|
|
<para>The source file</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><emphasis>file</emphasis>.idx</term>
|
|
<listitem>
|
|
<para>An intermediate file, typically removed after use</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><emphasis>file</emphasis>.snb</term>
|
|
<listitem>
|
|
<para>An intermediate file, typically removed after
|
|
use</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><emphasis>file</emphasis>.sdl</term>
|
|
<listitem>
|
|
<para>the output file</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>EXAMPLES</title>
|
|
<variablelist>
|
|
<varlistentry><term></term>
|
|
<listitem>
|
|
<para>Remove all files that resulted from previously
|
|
processing
|
|
the source file <literal>myFile.dbk</literal>:</para>
|
|
<para>% <command>dtdocbook</command> <literal>-r myFile.dbk</literal></para>
|
|
<para>or (without the .dbk extension)</para>
|
|
<para>% <command>dtdocbook</command> <literal>-r myFile</literal></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term></term>
|
|
<listitem>
|
|
<para>Process the file <literal>myFile.dbk</literal>:</para>
|
|
<para>% <command>dtdocbook</command> <literal>myFile.dbk</literal></para>
|
|
<para>or (without the .dbk extension)</para>
|
|
<para>% <command>dtdocbook</command> <literal>myFile</literal></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term></term>
|
|
<listitem>
|
|
<para>Process the file <literal>myFile.dbk</literal>
|
|
and write the
|
|
SDL output to <Filename>otherFile.sdl</Filename>:</para>
|
|
<para>% <command>dtdocbook</command><literal>-o otherFile.sdl
|
|
myFile.dbk</literal></para>
|
|
<para>or (without the .dbk extension)</para>
|
|
<para>% <command>dtdocbook</command><literal>-o otherFile.sdl
|
|
myFile</literal></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1>
|
|
<title>SEE ALSO</title>
|
|
<para>TO BE SUPPLIED</para>
|
|
</refsect1>
|
|
</refentry>
|