The following tools are used to process the documentation. Some might be optional, as noted.
This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. You need the SGML and the XML variant of the DocBook DTD of the same version. These will usually be in separate packages.
These are required by DocBook SGML but are distributed separately because they are maintained by ISO.
These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.
The minimum required version is currently 1.77.0, but it is recommended to use the latest available version for best results.
This is the base package of SGML processing. Note that we no longer need OpenJade, the DSSSL processor, only the OpenSP package for converting SGML to XML.
xmllint
This library and the xmllint
tool it contains are
used for processing XML. Many developers will already
have Libxml2 installed, because it is also
used when building the PostgreSQL code. Note, however,
that xmllint
might need to be installed from a
separate subpackage.
xsltproc
xsltproc
is an XSLT processor, that is, a program to
convert XML to other formats using XSLT stylesheets.
This is a program for converting, among other things, XML to PDF.
We have documented experience with several installation methods for the various tools that are needed to process the documentation. These will be described below. There might be some other packaged distributions for these tools. Please report package status to the documentation mailing list, and we will include that information here.
You can get away with not installing DocBook XML and the DocBook XSLT
stylesheets locally, because the required files will be downloaded from the
Internet and cached locally. This may in fact be the preferred solution if
your operating system packages provide only an old version of especially
the stylesheets or if no packages are available at all. See
the --nonet
option for xmllint
and xsltproc
for more information.
To install the required packages, use:
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
The FreeBSD Documentation Project is itself a heavy user of DocBook, so it comes as no surprise that there is a full set of “ports” of the documentation tools available on FreeBSD. The following ports need to be installed to build the documentation on FreeBSD.
textproc/docbook-sgml
textproc/docbook-xml
textproc/docbook-xsl
textproc/dsssl-docbook-modular
textproc/libxslt
textproc/fop
textproc/opensp
To install the required packages with pkg
, use:
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
When building the documentation from the doc
directory you'll need to use gmake
, because the
makefile provided is not suitable for FreeBSD's make
.
More information about the FreeBSD documentation tools can be found in the FreeBSD Documentation Project's instructions.
There is a full set of packages of the documentation tools available for Debian GNU/Linux. To install, simply use:
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
If you use MacPorts, the following will get you set up:
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
The manual installation process of the DocBook tools is somewhat complex, so if you have pre-built packages available, use them. We describe here only a standard setup, with reasonably standard installation paths, and no “fancy” features. For details, you should study the documentation of the respective package, and read SGML introductory material.
The installation of OpenSP offers a GNU-style
./configure; make; make install
build process.
Details can be found in the OpenSP source distribution. In a nutshell:
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install
Be sure to remember where you put the “default catalog”; you
will need it below. You can also leave it off, but then you will have to
set the environment variable SGML_CATALOG_FILES
to point
to the file whenever you use any programs from OpenSP later on. (This
method is also an option if OpenSP is already installed and you want to
install the rest of the toolchain locally.)
Obtain the DocBook V4.2 distribution.
Create the directory
/usr/local/share/sgml/docbook-4.2
and change
to it. (The exact location is irrelevant, but this one is
reasonable within the layout we are following here.)
$
mkdir /usr/local/share/sgml/docbook-4.2
$
cd /usr/local/share/sgml/docbook-4.2
Unpack the archive:
$
unzip -a ...../docbook-4.2.zip
(The archive will unpack its files into the current directory.)
Edit the file
/usr/local/share/sgml/catalog
(or whatever
you told jade during installation) and put a line like this
into it:
CATALOG "docbook-4.2/docbook.cat"
Download the ISO 8879 character entities archive, unpack it, and put the files in the same directory you put the DocBook files in:
$
cd /usr/local/share/sgml/docbook-4.2
$
unzip ...../ISOEnts.zip
Run the following command in the directory with the DocBook and ISO files:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(This fixes a mixup between the names used in the DocBook catalog file and the actual names of the ISO character entity files.)
configure
Before you can build the documentation you need to run the
configure
script as you would when building
the PostgreSQL programs themselves.
Check the output near the end of the run, it should look something
like this:
checking for onsgmls... onsgmls
checking for DocBook V4.2... yes
checking for dbtoepub... dbtoepub
checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for osx... osx
checking for fop... fop
If neither onsgmls
nor
nsgmls
were found then some of the following tests
will be skipped. nsgmls
is part of the OpenSP
package. You can pass the environment variable
NSGMLS
to configure to point
to the programs if they are not found automatically. If
“DocBook V4.2” was not found then you did not install
the DocBook DTD kit in a place where OpenSP can find it, or you have
not set up the catalog files correctly. See the installation hints
above.