START-INFO-DIR-ENTRY
* install: (install).           Convert DocBook into man pages and Texinfo
END-INFO-DIR-ENTRY

install
*******

Where to get docbook2X
**********************

   Please see the docbook2X web site
(http://docbook2x.sourceforge.net/).

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.

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 them here: CPAN XML module listing
     (//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/).

libxml2, libxslt
     If you are using OS distribution packages, you will need the
     development version of the packages, because docbook2X needs to
     compile XSLT extensions.

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

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

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

     Make sure you set up the XML (SGML) catalogs for the DTDs you
     install.

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.

Installation
************

   Unpack the tarball, then run `./configure', and then `make', `make
install', as usual.

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

Installation problems
=====================

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

  A:
     It's included in the docbook2X package. If Perl says it cannot
     find it, something went wrong with the install, or you tried to
     run the docbook2X Perl scripts in some other directory without
     installing.  If you want to do the latter, you have to set
     `PERLLIB' manually to point to `WHERE-YOU-PUT-DOCBOOK2X/perl/XML'.

  Q:
     I get an error when compiling the things under `libxslt/'. Or a
     segmentation fault occurs running db2x_xsltproc.

  A:
     Either I made a bad mistake in the code, or the libxslt people
     changed their programming interfaces. You can try using the same
     version of libxslt (and libxml) I used when this version of
     docbook2X was released and see if that helps. Please tell me about
     this, so that I can release a new update to docbook2X.

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

