Blob Blame History Raw
docbook2X installation
**********************

1 Installation
**************

After checking that you have the necessary prerequisites (*note
Dependencies on other software::), unpack the tarball, then run
'./configure', and then 'make', 'make install', as usual.

     *Note*

     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 'xslt/' subdirectory.

   (The last 'make install' 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.)

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

   You need GNU make to build docbook2X properly.  

   If you are using the CVS version, you will also need the autoconf
and automake tools, and must run './autogen.sh' first.  But see also
the note below about the CVS version.

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

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

   If you are using a Java-based XSLT processor, you need to use pass
'--with-xslt-processor=saxon' for SAXON, or
'--with-xslt-processor=xalan-j' 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 './configure' to tell it where the JARs are.  See
'./configure --help' for details.

   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.



1.1 Installation problems
=========================

  Q:
     Where is 'XML::Handler::SGMLSpl'?

  A:
     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.

     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.

  Q:
     'db2x_xsltproc' tells me that 'one input document is required'
     when building docbook2X.

  A:
     Use GNU make to build docbook2X (as opposed to BSD make).

     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.

  Q:
     When docbook2X attempts to build its documentation, I get errors
     about "attempting to load network entity", etc.

  A:
     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.

     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).

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

  Q:
     I cannot build from CVS.

  A:
     If the problem is related to HTML files, then you must pass
     '--with-html-xsl' to 'configure'.  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.)

   For other docbook2X problems, please also look at its main
documentation.

2 Dependencies on other software
********************************

To use docbook2X you need:

A reasonable Unix system, with Perl 5
     docbook2X can work on Linux, FreeBSD, Solaris, and Cygwin on
     Windows.

     A C compiler is required to compile a small ANSI C program
     ('utf8trans').

XML-NamespaceSupport, XML-SAX, XML-Parser and XML-SAX-Expat (Perl modules)
     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.

     You can get all the Perl modules here: CPAN XML module listing
     (http://www.cpan.org/modules/by-category/11_String_Lang_Text_Proc/XML/).

iconv
     If you are running Linux glibc, you already have it.  Otherwise,
     see the GNU libiconv home page
     (http://www.gnu.org/software/libiconv/).

XSLT 1.0 processor
     You have a choice of:

    libxslt
          See the libxml2, libxslt home page (http://xmlsoft.org/).

    SAXON
          See the SAXON home page (http://saxon.sourceforge.net/).

    Xalan-Java
          See the Xalan-Java home page (http://xml.apache.org/xalan-j/).

     For the Java-based processors (SAXON and Xalan-Java), you will
     also need(1) the Apache XML Commons
     (http://xml.apache.org/commons/) distribution.  This adds XML
     catalogs support to any Java-based processor.

     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.)

     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.

DocBook XML DTD
     Make sure you set up the XML catalogs for the DTDs you install.

     The DocBook: The Definitive Guide website
     (http://www.docbook.org/) has more information.

     You may also need the SGML DTD if your documents are SGML rather
     than XML.

Norman Walsh's DocBook XSL stylesheets
     See the Open DocBook Repository (http://docbook.sourceforge.net/).

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

   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.  

   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).

   ---------- Footnotes ----------

   (1) 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.