<?xml version="1.0" encoding="utf-8" ?>
<!-- vim: sta et sw=2
-->

<sect1 id="install-procedure">
<sect1info>
<abstract role="texinfo-node">
  <para>Package install procedure</para>
</abstract>
</sect1info>
<title>Installation</title>

<indexterm><primary>docbook2X package</primary></indexterm>
<indexterm><primary>installation</primary></indexterm>

<para>
After checking that you have the 
<link linkend="dependencies">necessary prerequisites</link>,
unpack the tarball, then run <userinput>./configure</userinput>, and
then <userinput>make</userinput>, <userinput>make install</userinput>,
as usual.  </para>

<note>
<para>
<indexterm><primary>pure XSLT</primary></indexterm>
If you intend to use only the pure XSLT version of docbook2X,
then you do not need to compile or build the package at all.
Simply unpack the tarball, and point your XSLT processor
to the XSLT stylesheets under the <filename>xslt/</filename>
subdirectory.
</para>
</note>

<para>
(The last <userinput>make install</userinput> step, to install
the files of the package onto the filesystem, is optional.  You may use
docbook2X from its own directory after building it, although in that case, 
when invoking docbook2X, you will have to specify some paths manually
on the command-line.)
</para>

<para>
You may also want to run <userinput>make check</userinput> to do some
checks that the package is working properly.  Typing
<userinput>make -W docbook2X.xml man texi</userinput> in
the <filename>doc/</filename> directory will rebuild
docbook2X’s own documentation, and can serve as an additional check.
</para>

<para>
You need GNU make to build docbook2X properly.
</para>

<indexterm><primary>CVS</primary></indexterm>
<para>
If you are using the CVS version, you will also need the autoconf and automake
tools, and must run <userinput>./autogen.sh</userinput> first.  But
see also the note below about the CVS version.
</para>

<para>
<indexterm><primary>HTML documentation</primary></indexterm>
If you want to (re-)build HTML documentation (after having installed Norman Walsh’s DocBook XSL stylesheets), pass <option>--with-html-xsl</option>
to <userinput>./configure</userinput>.  You do not really need this,
since docbook2X releases already contain pre-built HTML documentation.
</para>

<para>
Some other packages also call their conversion programs
<command>docbook2man</command> and <command>docbook2texi</command>;
you can use the <option>--program-transform-name</option> parameter to 
<userinput>./configure</userinput> if you do not want docbook2X to clobber
over your existing <command>docbook2man</command> or 
<command>docbook2texi</command>.
</para>

<para>
If you are using a Java-based XSLT processor,
you need to use pass <option>--with-xslt-processor=saxon</option> for
SAXON, or <option>--with-xslt-processor=xalan-j</option> for
Xalan-Java.  (The default is for libxslt.)
In addition, since the automatic check for the installed JARs is not
very intelligent, you will probably need to pass some options
to <userinput>./configure</userinput> to tell it where the JARs are.
See <userinput>./configure --help</userinput> for details.
</para>

<para>
The docbook2X package supports VPATH builds (building in a location 
other than the source directory), but any newly generated documentation
will not end up in the right place for installation and redistribution.
Cross compilation is not supported at all.
</para>



<sect2 id="install-problems">
<sect2info>
<abstract role="texinfo-node">
  <para>Possible problems when installing and building docbook2X
        and how to solve them</para>
</abstract>
</sect2info>
<title>Installation problems</title>

<indexterm><primary>problems</primary></indexterm>

<qandaset defaultlabel="qanda">

<qandaentry>
<question>
<para>Where is <classname>XML::Handler::SGMLSpl</classname>?</para>
</question>

<answer>
<para>
It’s included in the docbook2X package.  
If Perl says it cannot find it,
then that is a bug in the docbook2X distribution.
Please report it.
</para>

<para>
In older versions of docbook2X, the SGMLSpl module
had to be installed, or specified manually on the Perl command line.
That is no longer the case.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
&db2x_xsltproc; tells me that <quote>one input document is required</quote>
when building docbook2X.
</para>
</question>

<answer>
<para>
Use GNU make to build docbook2X (as opposed to BSD make).
</para>

<para>
I could fix this incompatibility in the docbook2X make files,
but some of the default automake rules have the same problem,
so I didn’t bother.
</para>

</answer>
</qandaentry>

<qandaentry>
<question>
<para>
When docbook2X attempts to build its documentation,
I get errors about “attempting to load network entity”, etc.
</para>
</question>

<answer>
<para>
You will need to set up the XML catalogs for the DocBook XML DTDs correctly.
This tells the XSLT processor where to find the DocBook DTDs on your system.
Recent Linux distributions should already have this done for you.
</para>

<para>
This error (or rather, warning) is harmless in the case of docbook2X
documentation — it does not actually require the DTD to build.
But your other DocBook documents might (mainly because they use
the ISO entities).
</para>

<para>
libxml also understands SGML catalogs, but last time I tried it
there was some bug that stopped it from working.  Your Mileage May Vary.
</para>

</answer>

</qandaentry>

<qandaentry>
<question><para>I cannot build from CVS.</para></question>
<answer>
<para>
If the problem is related to HTML files, then you must
pass <option>--with-html-xsl</option> to <command>configure</command>.
The problem is that the HTML files are automatically generated
from the XML source and are not in CVS, but the Makefile still
tries to install them.  (This issue does not appear when
building from release tarballs.)
</para>
</answer>
</qandaentry>

</qandaset>

<para>
For other docbook2X problems, please also look at its main documentation.
</para>
</sect2>
</sect1>

<sect1 id="dependencies">
<sect1info>
  <abstract role="texinfo-node">
    <para>Other software packages that docbook2X needs</para>
  </abstract>
</sect1info>
<title>Dependencies on other software</title>

<indexterm><primary>dependencies</primary></indexterm>
<indexterm><primary>prerequisites</primary></indexterm>
<indexterm><primary>docbook2X package</primary></indexterm>

  <para>
    To use docbook2X you need:

    <variablelist>
      <varlistentry>
        <term>A reasonable Unix system, with Perl 5</term>
        <listitem>
<indexterm><primary>Windows</primary></indexterm>
          <para>
            docbook2X can work on Linux, FreeBSD, Solaris, and Cygwin on Windows.
          </para>

          <para>
            A C compiler is required to compile
            a small ANSI C program (&utf8trans;).  
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>XML-NamespaceSupport, XML-SAX, XML-Parser and
XML-SAX-Expat (Perl modules)</term>
        <listitem>
          <para>
<indexterm><primary>Perl</primary></indexterm>
            The last two are optional: they add a Perl interface to the 
            C-based XML parser Expat.  It is recommended that you install them 
            anyway; otherwise, the fallback Perl-based XML parser
            makes docbook2X real slow.
          </para>

          <para>
            You can get all the Perl modules here: <ulink url="http://www.cpan.org/modules/by-category/11_String_Lang_Text_Proc/XML/">CPAN XML module listing</ulink>.
          </para>
          
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>iconv</term>

        <listitem>
<indexterm><primary><command>iconv</command></primary></indexterm>
          <para>
            If you are running Linux glibc, you already have it.
            Otherwise, see <ulink
            url="http://www.gnu.org/software/libiconv/">the GNU libiconv home page</ulink>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>XSLT 1.0 processor</term>
        <listitem>
          <para>
<indexterm><primary>SAXON</primary></indexterm>
<indexterm><primary>Xalan-Java</primary></indexterm>
<indexterm><primary>libxslt</primary></indexterm>
            You have a choice of:
            
            <variablelist>
              <varlistentry>
                <term>libxslt</term>
                <listitem>
                  <para>See the <ulink url="http://xmlsoft.org/">
                        libxml2, libxslt home page</ulink>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>SAXON</term>
                <listitem>
                  <para>See <ulink url="http://saxon.sourceforge.net/">
                        the SAXON home page</ulink>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>Xalan-Java</term>
                <listitem>
                  <para>See <ulink url="http://xml.apache.org/xalan-j/">
                        the Xalan-Java home page</ulink>.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </para>

          <para>
<indexterm><primary>catalog</primary></indexterm>
            For the Java-based processors (SAXON and Xalan-Java),
            you will also need<footnote><para>Strictly speaking this component is not required, but if you do not have it, you will almost certainly have your computer downloading large XML files from the Internet all the time, as portable XML files will not refer directly to cached local copies of the required files.</para></footnote> <ulink url="http://xml.apache.org/commons/">the Apache 
            XML Commons</ulink> distribution.
            This adds XML catalogs support to any Java-based 
            processor.
          </para>

          <para>
            Out of the three processors, libxslt is recommended.
            (I would have added support for other XSLT processors,
            but only these three seem to have proper XML catalogs
            support.)
          </para>
            
          <para>
            Unlike previous versions of docbook2X, these Java-based
            processors can work almost out-of-the-box.  Also docbook2X
            no longer needs to compile XSLT extensions,
            so you if you use an OS distribution package of libxslt,
            you do not need the development versions of the
            library any more.
          </para>
        </listitem>
      </varlistentry>
          
      <varlistentry>
        <term>DocBook XML DTD</term>

        <listitem>
<indexterm><primary>DocBook</primary></indexterm>
          <para>
            Make sure you set up the XML catalogs for the DTDs
            you install.
          </para>
          
          <para>The <ulink url="http://www.docbook.org/"><citetitle>DocBook: The Definitive Guide</citetitle> website</ulink> has more information.
          </para>

          <para>You may also need the SGML DTD if your documents are SGML
          rather than XML.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Norman Walsh’s DocBook XSL stylesheets</term>

        <listitem>
<indexterm><primary>HTML documentation</primary></indexterm>
          <para>See the <ulink url="http://docbook.sourceforge.net/">Open DocBook Repository</ulink>.</para>

          <para>
            This is optional and is only used to build documentation in HTML format.  In your XML catalog, point the URI in <filename>doc/ss-html.xsl</filename>
            to a local copy of the stylesheets.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>

  <para>
    For all the items above, it will be easier for you
    to install the OS packaging of the software (e.g. Debian packages),
    than to install them manually.  But be aware that sometimes the OS
    package may not be for an up-to-date version of the software.
  </para>

<indexterm><primary>Windows</primary></indexterm>
  <para>
    If you cannot satisfy all the prerequisites above (say you are on 
    a vanilla Win32 system), then you will not be able to “build”
    docbook2X properly, but if you are knowledgeable, you can still
    salvage its parts (e.g. the XSLT stylesheets, which can be run alone).
  </para>
  
</sect1>