<!-- $XConsortium: infogen.sgm /main/8 1996/11/15 15:37:49 cdedoc $ -->
<!-- (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.dtdocbook2infolib">]]>
<RefMeta>
<refentrytitle>dtdocbook2infolib</refentrytitle>
<manvolnum>user cmd</manvolnum></refmeta>
<refnamediv>
<refname><command>dtdocbook2infolib</command></refname>
<refpurpose>access DtInfo Toolkit functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>dtdocbook2infolib</command>
<arg choice="opt">-h</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>dtdocbook2infolib admin</command>
<arg choice="opt">-h</arg>
<arg choice="plain">-L <replaceable>Locale</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>dtdocbook2infolib build</command>
<arg choice="opt">-h</arg>
<arg choice="plain">-L <replaceable>Locale</replaceable></arg>
<arg choice="opt">-T <replaceable>TmpDir</replaceable></arg>
<arg choice="opt">-m <replaceable>CatalogFile</replaceable></arg>
<arg choice="plain">-l <replaceable>Library</replaceable></arg>
<arg choice="plain">-d <replaceable>LibraryDescription</replaceable></arg>
<arg choice="plain">-n <replaceable>LibraryShortName</replaceable></arg>
<arg choice="plain"><replaceable>Bookcase</replaceable> ...</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>dtdocbook2infolib tocgen</command>
<arg choice="opt">-h</arg>
<arg choice="plain">-L <replaceable>Locale</replaceable></arg>
<arg choice="opt">-T <replaceable>TmpDir</replaceable></arg>
<arg choice="opt">-m <replaceable>CatalogFile</replaceable></arg>
<arg choice="opt">-id <replaceable>TOCid</replaceable></arg>
<arg choice="opt">-title <replaceable>TOCtitle</replaceable></arg>
<arg choice="plain"><replaceable>document</replaceable> ...</arg>
<arg choice="plain">-f <replaceable>TOCfile</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>dtdocbook2infolib update</command>
<arg choice="opt">-h</arg>
<arg choice="plain">-L <replaceable>Locale</replaceable></arg>
<arg choice="opt">-T <replaceable>TmpDir</replaceable></arg>
<arg choice="opt">-m <replaceable>CatalogFile</replaceable></arg>
<arg choice="plain">-b <replaceable>BookcaseName</replaceable></arg>
<arg choice="plain">-l <replaceable>library</replaceable></arg>
<arg choice="plain"><replaceable>stylesheet</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>dtdocbook2infolib validate</command>
<arg choice="opt">-h</arg>
<arg choice="plain">-L <replaceable>Locale</replaceable></arg>
<arg choice="opt">-T <replaceable>TmpDir</replaceable></arg>
<arg choice="opt">-m <replaceable>CatalogFile</replaceable></arg>
<arg choice="plain"><replaceable>SGMLdocument</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>The DtInfo Toolkit command, <command>dtdocbook2infolib</command>, is used to create and modify
hypertext information libraries.
<command>dtdocbook2infolib</command> implements its functions
through a set of subcommands:
</para>
<variablelist>
<varlistentry><term><command>admin</command></term>
<listitem>
<para>Modify the contents of an information library by copying, renaming,
rearranging, or removing bookcases. You can also list the contents of a
library.
</para>
</listitem>
</varlistentry>
<varlistentry><term><command>build</command></term>
<listitem>
<para>Build a DtInfo information library from bookcase
specifications.
</para>
</listitem>
</varlistentry>
<varlistentry><term><command>tocgen</command></term>
<listitem>
<para>Generate a hypertext table of contents for a book.
</para>
</listitem>
</varlistentry>
<varlistentry><term><command>update</command></term>
<listitem>
<para>Replace existing style sheet information in a bookcase.
</para>
</listitem>
</varlistentry>
<varlistentry><term><command>validate</command></term>
<listitem>
<para>Verify that a document conforms to SGML and to the
DocBook.DTD.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<para>The following options are available:
</para>
<variablelist>
<varlistentry><term><literal>-h</literal></term>
<listitem><para>Displays a help message for each available option.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-L</literal> <replaceable>Locale</replaceable></term>
<listitem><para>Specifies the locale of the information library.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-T</literal> <replaceable>TmpDir</replaceable></term>
<listitem><para>Specifies the directory in which temporary files are placed during the
build process. The default is to use the environment variable
<systemitem class="environvar">TMPDIR</systemitem>. If variable
<systemitem class="environvar">TMPDIR</systemitem> is not set,
<filename>/tmp</filename> is used.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-m</literal> <replaceable>CatalogFile</replaceable></term>
<listitem><para>Specifies a catalog file conforming to the SGML Open specification for
resolving SGML entities. You can use multiple
<literal>-m</literal> options to specify as many
<replaceable>CatalogFile</replaceable>s as you wish.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-l</literal> <replaceable>Library</replaceable></term>
<listitem><para>Specifies the location of the information library to build.
<replaceable>Library</replaceable> is the name of the directory that
contains the built bookcase(s).
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-d</literal> <replaceable>LibraryDescription</replaceable></term>
<listitem><para><replaceable>LibraryDescription</replaceable> is a brief description of
the information library to be built.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-n</literal> <replaceable>LibraryShortName</replaceable></term>
<listitem><para><replaceable>LibraryShortName</replaceable> specifies an abbreviated name for
the information library to be built.
</para></listitem>
</varlistentry>
<varlistentry><term><replaceable>bookcase</replaceable></term>
<listitem><para>The SGML bookcase instance conforming to the
dtinfoBook.dtd.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-f</literal> <replaceable>TOCfile</replaceable></term>
<listitem><para>Specifies the SGML instance of a hypertext table of contents conforming
to the dtinfoTOC.dtd.
</para></listitem>
</varlistentry>
<varlistentry><term><replaceable>document</replaceable></term>
<listitem><para>A DocBook SGML source file.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-b</literal> <replaceable>BookcaseName</replaceable></term>
<listitem><para>The name of the bookcase whose style sheet information will be updated.
The content of the <Symbol>BOOKCASENAME</Symbol> element in the
dtinfoBook.dtd.
</para></listitem>
</varlistentry>
<varlistentry><term><replaceable>stylesheet</replaceable></term>
<listitem><para>The style sheet that is to be updated in the bookcase.
</para></listitem>
</varlistentry>
<varlistentry><term><replaceable>SGMLdocument</replaceable></term>
<listitem><para>Any SGML document to be validated.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-id</literal> <replaceable>TOCid</replaceable></term>
<listitem><para>The unique identifier of the hypertext table of contents
document.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>-title</literal> <replaceable>TOCtitle</replaceable></term>
<listitem><para>The title of the table of contents. This title will be
displayed in the DtInfo Browser.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>admin</title>
<para>The <command>admin</command> subcommand is an interactive script for
modifying an existing information library without rebuilding it. It
displays a command line menu from which you select one of the following
administration functions to perform on a specified information library:
</para>
<itemizedlist>
<listitem><para>Copy a bookcase from another library.
</para></listitem>
<listitem><para>Remove a bookcase from a library.
</para></listitem>
<listitem><para>List the bookcases in a library.
</para></listitem>
<listitem><para>Rename a bookcase.
</para></listitem>
<listitem><para>Rearrange bookcases within a library.
</para></listitem>
</itemizedlist>
<refsect2>
<title>Example</title>
<para>Enter the <command>dtdocbook2infolib admin -L en_US.UTF-8</command> command in a shell window:
</para>
<literallayout><command>dtdocbook2infolib admin -L en_US.UTF-8</command>
</literallayout>
<para>The following menu appears:
</para>
<literallayout>
1) Copy a bookcase from another library
2) Remove a bookcase
3) List bookcases in a library
4) Rename a bookcase
5) Rearrange bookcases in a library
6) Exit
Please enter your choice [1-6]
</literallayout>
<para>Enter the number associated with the administrative task you
want to perform.
<command>dtdocbook2infolib admin -L en_US.UTF-8</command> prompts for additional input as required.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>build</title>
<para>The <command>build</command> subcommand compiles a bookcase specification into a
hypertext database. It validates the hypertext links, the identifier
uniqueness, and the hierarchical structure of the bookcase elements.
It also creates a full-text search index.
</para>
<refsect2>
<title>Example</title>
<para>Enter the <command>dtdocbook2infolib build -L en_US.UTF-8</command>
command in a shell window.
</para>
<para>To build an information library containing multiple bookcases,
an example command might be:
</para>
<programlisting>
<userinput>dtdocbook2infolib build -L en_US.UTF-8 -l
</userinput> <replaceable>UNIXLib</replaceable><userinput> -T
</userinput> <filename>/usr/pers</filename><userinput>
</userinput> <replaceable>ProgBooks</replaceable><userinput>
</userinput> <replaceable>RefBooks</replaceable><userinput>
</userinput> <replaceable>UAdminBooks</replaceable>
</programlisting>
<para>This <command>build</command> command creates a document database from
three bookcases (<replaceable>ProgBooks</replaceable>,
<replaceable>RefBooks</replaceable>, and
<replaceable>UAdminBooks</replaceable>) and reports any errors. It uses
<filename>/usr/pers</filename> to store temporary intermediate files,
and it deposits the database in a directory (library) called
<replaceable>UNIXLib</replaceable>.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>tocgen</title>
<para>The <command>tocgen</command> subcommand reads the SGML-conforming
source file(s) for a book and generates a hypertext table of contents.
</para>
<refsect2>
<title>Example</title>
<para>Enter the <command>dtdocbook2infolib tocgen -L en_US.UTF-8</command>
command in a shell window.
</para>
<para>To generate a hypertext table of contents for a book containing six SGML
book source files, each of which contains a separate chapter, an example
command might be:
</para>
<programlisting><userinput>dtdocbook2infolib tocgen -L en_US.UTF-8 -T
</userinput> <filename>/usr/pers</filename><userinput> -f
</userinput> <replaceable>Perl.TOC</replaceable><userinput> -id
</userinput> <replaceable>Perl0594</replaceable>
<userinput>-title</userinput> <replaceable>"Perl Table of Contents" Perl.01 Perl.02 Perl.03 Perl.04 Perl.05 Perl.06</replaceable>
</programlisting>
<para>This <command>tocgen</command> command generates a table of contents file named
<replaceable>Perl.TOC</replaceable> with the unique identifier
<replaceable>Perl0594</replaceable> and the title
<replaceable>PerlTable of Contents</replaceable>.
<command>tocgen</command> parses the files
<replaceable>Perl.01</replaceable>,
<replaceable>Perl.02</replaceable>,
<replaceable>Perl.03</replaceable>,
<replaceable>Perl.04</replaceable>,
<replaceable>Perl.05</replaceable>, and
<replaceable>Perl.06</replaceable> to produce the TOC.
</para>
<para>The <command>tocgen</command> process uses
<filename>/usr/pers</filename> to store temporary intermediate files
during processing.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>update</title>
<para>The <command>dtdocbook2infolib update -L en_US.UTF-8</command>
command dynamically replaces existing style sheets in the DtInfo document
database.
</para>
<refsect2>
<title>Example</title>
<para>Enter the <command>dtdocbook2infolib update -L en_US.UTF-8</command>
command in a shell window.
</para>
<para>Here is an example of a <command>dtdocbook2infolib update -L en_US.UTF-8
</command>
command used to reformat the documents and/or document sections that use the
specified style sheet:
</para>
<programlisting><userinput>dtdocbook2infolib update -L en_US.UTF-8 -T
</userinput> <filename>/usr/pers</filename><userinput> -b
</userinput> <replaceable>ICE9</replaceable><userinput> -l
</userinput> <replaceable>Brunn style</replaceable>
</programlisting>
<para>This <command>update</command> command reformats the documents or
document sections in the <replaceable>Brunn</replaceable> information
library that use the style sheet named <replaceable>style</replaceable>,
that is specified in the bookcase named <replaceable>ICE9</replaceable>.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>validate</title>
<para>The <command>dtdocbook2infolib validate -L en_US.UTF-8</command>
command performs SGML validation on bookcase specifications, on individual book
source files, or any SGML document.
</para>
<refsect2>
<title>Examples</title>
<para>Enter the <command>dtdocbook2infolib validate -L en_US.UTF-8</command>
in a shell window.
</para>
<para>Here is an example of a <command>dtdocbook2infolib validate -L en_US.UTF-8
</command>
command that performs validation on three SGML book source files:
</para>
<programlisting>
<userinput>dtdocbook2infolib validate -L en_US.UTF-8
</userinput> <replaceable>03.Structure.N</replaceable><userinput>
</userinput> <replaceable>04.Process.N</replaceable><userinput>
</userinput> <replaceable>05.BookArea.N</replaceable>
</programlisting>
<para>This <command>validate</command> command verifies the SGML compliance of
the three files, <replaceable>03.Structure.N</replaceable>,
<replaceable>04.Process.N</replaceable>, and <replaceable>05.BookArea.N</replaceable>,
based on their DTD(s).
</para>
</refsect2>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>&cdeman.dtinfo;,
&cdeman.dtinfoBook.dtd;,
&cdeman.dtinfoStyle.dtd;,
&cdeman.dtinfoTOC.dtd;
</Para>
</refsect1></refentry>
