|
Packit |
e4b6da |
docbook2X installation
|
|
Packit |
e4b6da |
**********************
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
1 Installation
|
|
Packit |
e4b6da |
**************
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
After checking that you have the necessary prerequisites (*note
|
|
Packit |
e4b6da |
Dependencies on other software::), unpack the tarball, then run
|
|
Packit |
e4b6da |
'./configure', and then 'make', 'make install', as usual.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
*Note*
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you intend to use only the pure XSLT version of docbook2X, then
|
|
Packit |
e4b6da |
you do not need to compile or build the package at all. Simply
|
|
Packit |
e4b6da |
unpack the tarball, and point your XSLT processor to the XSLT
|
|
Packit |
e4b6da |
stylesheets under the 'xslt/' subdirectory.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
(The last 'make install' step, to install the files of the package
|
|
Packit |
e4b6da |
onto the filesystem, is optional. You may use docbook2X from its own
|
|
Packit |
e4b6da |
directory after building it, although in that case, when invoking
|
|
Packit |
e4b6da |
docbook2X, you will have to specify some paths manually on the
|
|
Packit |
e4b6da |
command-line.)
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
You may also want to run 'make check' to do some checks that the
|
|
Packit |
e4b6da |
package is working properly. Typing 'make -W docbook2X.xml man texi' in
|
|
Packit |
e4b6da |
the 'doc/' directory will rebuild docbook2X's own documentation, and
|
|
Packit |
e4b6da |
can serve as an additional check.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
You need GNU make to build docbook2X properly.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you are using the CVS version, you will also need the autoconf
|
|
Packit |
e4b6da |
and automake tools, and must run './autogen.sh' first. But see also
|
|
Packit |
e4b6da |
the note below about the CVS version.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you want to (re-)build HTML documentation (after having installed
|
|
Packit |
e4b6da |
Norman Walsh's DocBook XSL stylesheets), pass '--with-html-xsl' to
|
|
Packit |
e4b6da |
'./configure'. You do not really need this, since docbook2X releases
|
|
Packit |
e4b6da |
already contain pre-built HTML documentation.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Some other packages also call their conversion programs
|
|
Packit |
e4b6da |
'docbook2man' and 'docbook2texi'; you can use the
|
|
Packit |
e4b6da |
'--program-transform-name' parameter to './configure' if you do not
|
|
Packit |
e4b6da |
want docbook2X to clobber over your existing 'docbook2man' or
|
|
Packit |
e4b6da |
'docbook2texi'.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you are using a Java-based XSLT processor, you need to use pass
|
|
Packit |
e4b6da |
'--with-xslt-processor=saxon' for SAXON, or
|
|
Packit |
e4b6da |
'--with-xslt-processor=xalan-j' for Xalan-Java. (The default is for
|
|
Packit |
e4b6da |
libxslt.) In addition, since the automatic check for the installed
|
|
Packit |
e4b6da |
JARs is not very intelligent, you will probably need to pass some
|
|
Packit |
e4b6da |
options to './configure' to tell it where the JARs are. See
|
|
Packit |
e4b6da |
'./configure --help' for details.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
The docbook2X package supports VPATH builds (building in a location
|
|
Packit |
e4b6da |
other than the source directory), but any newly generated documentation
|
|
Packit |
e4b6da |
will not end up in the right place for installation and redistribution.
|
|
Packit |
e4b6da |
Cross compilation is not supported at all.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
1.1 Installation problems
|
|
Packit |
e4b6da |
=========================
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Q:
|
|
Packit |
e4b6da |
Where is 'XML::Handler::SGMLSpl'?
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
A:
|
|
Packit |
e4b6da |
It's included in the docbook2X package. If Perl says it cannot
|
|
Packit |
e4b6da |
find it, then that is a bug in the docbook2X distribution. Please
|
|
Packit |
e4b6da |
report it.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
In older versions of docbook2X, the SGMLSpl module had to be
|
|
Packit |
e4b6da |
installed, or specified manually on the Perl command line. That
|
|
Packit |
e4b6da |
is no longer the case.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Q:
|
|
Packit |
e4b6da |
'db2x_xsltproc' tells me that 'one input document is required'
|
|
Packit |
e4b6da |
when building docbook2X.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
A:
|
|
Packit |
e4b6da |
Use GNU make to build docbook2X (as opposed to BSD make).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
I could fix this incompatibility in the docbook2X make files, but
|
|
Packit |
e4b6da |
some of the default automake rules have the same problem, so I
|
|
Packit |
e4b6da |
didn't bother.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Q:
|
|
Packit |
e4b6da |
When docbook2X attempts to build its documentation, I get errors
|
|
Packit |
e4b6da |
about "attempting to load network entity", etc.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
A:
|
|
Packit |
e4b6da |
You will need to set up the XML catalogs for the DocBook XML DTDs
|
|
Packit |
e4b6da |
correctly. This tells the XSLT processor where to find the
|
|
Packit |
e4b6da |
DocBook DTDs on your system. Recent Linux distributions should
|
|
Packit |
e4b6da |
already have this done for you.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
This error (or rather, warning) is harmless in the case of
|
|
Packit |
e4b6da |
docbook2X documentation -- it does not actually require the DTD to
|
|
Packit |
e4b6da |
build. But your other DocBook documents might (mainly because
|
|
Packit |
e4b6da |
they use the ISO entities).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
libxml also understands SGML catalogs, but last time I tried it
|
|
Packit |
e4b6da |
there was some bug that stopped it from working. Your Mileage May
|
|
Packit |
e4b6da |
Vary.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Q:
|
|
Packit |
e4b6da |
I cannot build from CVS.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
A:
|
|
Packit |
e4b6da |
If the problem is related to HTML files, then you must pass
|
|
Packit |
e4b6da |
'--with-html-xsl' to 'configure'. The problem is that the HTML
|
|
Packit |
e4b6da |
files are automatically generated from the XML source and are not
|
|
Packit |
e4b6da |
in CVS, but the Makefile still tries to install them. (This issue
|
|
Packit |
e4b6da |
does not appear when building from release tarballs.)
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
For other docbook2X problems, please also look at its main
|
|
Packit |
e4b6da |
documentation.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
2 Dependencies on other software
|
|
Packit |
e4b6da |
********************************
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
To use docbook2X you need:
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
A reasonable Unix system, with Perl 5
|
|
Packit |
e4b6da |
docbook2X can work on Linux, FreeBSD, Solaris, and Cygwin on
|
|
Packit |
e4b6da |
Windows.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
A C compiler is required to compile a small ANSI C program
|
|
Packit |
e4b6da |
('utf8trans').
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
XML-NamespaceSupport, XML-SAX, XML-Parser and XML-SAX-Expat (Perl modules)
|
|
Packit |
e4b6da |
The last two are optional: they add a Perl interface to the
|
|
Packit |
e4b6da |
C-based XML parser Expat. It is recommended that you install them
|
|
Packit |
e4b6da |
anyway; otherwise, the fallback Perl-based XML parser makes
|
|
Packit |
e4b6da |
docbook2X real slow.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
You can get all the Perl modules here: CPAN XML module listing
|
|
Packit |
e4b6da |
(http://www.cpan.org/modules/by-category/11_String_Lang_Text_Proc/XML/).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
iconv
|
|
Packit |
e4b6da |
If you are running Linux glibc, you already have it. Otherwise,
|
|
Packit |
e4b6da |
see the GNU libiconv home page
|
|
Packit |
e4b6da |
(http://www.gnu.org/software/libiconv/).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
XSLT 1.0 processor
|
|
Packit |
e4b6da |
You have a choice of:
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
libxslt
|
|
Packit |
e4b6da |
See the libxml2, libxslt home page (http://xmlsoft.org/).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
SAXON
|
|
Packit |
e4b6da |
See the SAXON home page (http://saxon.sourceforge.net/).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Xalan-Java
|
|
Packit |
e4b6da |
See the Xalan-Java home page (http://xml.apache.org/xalan-j/).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
For the Java-based processors (SAXON and Xalan-Java), you will
|
|
Packit |
e4b6da |
also need(1) the Apache XML Commons
|
|
Packit |
e4b6da |
(http://xml.apache.org/commons/) distribution. This adds XML
|
|
Packit |
e4b6da |
catalogs support to any Java-based processor.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Out of the three processors, libxslt is recommended. (I would
|
|
Packit |
e4b6da |
have added support for other XSLT processors, but only these three
|
|
Packit |
e4b6da |
seem to have proper XML catalogs support.)
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Unlike previous versions of docbook2X, these Java-based processors
|
|
Packit |
e4b6da |
can work almost out-of-the-box. Also docbook2X no longer needs to
|
|
Packit |
e4b6da |
compile XSLT extensions, so you if you use an OS distribution
|
|
Packit |
e4b6da |
package of libxslt, you do not need the development versions of the
|
|
Packit |
e4b6da |
library any more.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
DocBook XML DTD
|
|
Packit |
e4b6da |
Make sure you set up the XML catalogs for the DTDs you install.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
The DocBook: The Definitive Guide website
|
|
Packit |
e4b6da |
(http://www.docbook.org/) has more information.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
You may also need the SGML DTD if your documents are SGML rather
|
|
Packit |
e4b6da |
than XML.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Norman Walsh's DocBook XSL stylesheets
|
|
Packit |
e4b6da |
See the Open DocBook Repository (http://docbook.sourceforge.net/).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
This is optional and is only used to build documentation in HTML
|
|
Packit |
e4b6da |
format. In your XML catalog, point the URI in 'doc/ss-html.xsl'
|
|
Packit |
e4b6da |
to a local copy of the stylesheets.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
For all the items above, it will be easier for you to install the OS
|
|
Packit |
e4b6da |
packaging of the software (e.g. Debian packages), than to install them
|
|
Packit |
e4b6da |
manually. But be aware that sometimes the OS package may not be for an
|
|
Packit |
e4b6da |
up-to-date version of the software.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you cannot satisfy all the prerequisites above (say you are on a
|
|
Packit |
e4b6da |
vanilla Win32 system), then you will not be able to "build" docbook2X
|
|
Packit |
e4b6da |
properly, but if you are knowledgeable, you can still salvage its parts
|
|
Packit |
e4b6da |
(e.g. the XSLT stylesheets, which can be run alone).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
---------- Footnotes ----------
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
(1) Strictly speaking this component is not required, but if you do
|
|
Packit |
e4b6da |
not have it, you will almost certainly have your computer downloading
|
|
Packit |
e4b6da |
large XML files from the Internet all the time, as portable XML files
|
|
Packit |
e4b6da |
will not refer directly to cached local copies of the required files.
|
|
Packit |
e4b6da |
|