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.5; you cannot use later or earlier versions. You need the XML variant of the DocBook DTD, not the SGML variant.
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.
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
To install the required packages with pkg, use:
pkg install docbook-xml docbook-xsl fop libxslt
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.
There is a full set of packages of the documentation tools available for Debian GNU/Linux. To install, simply use:
apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
On macOS, you can build the HTML and man documentation without installing anything extra. If you want to build PDFs or want to install a local copy of DocBook, you can get those from your preferred package manager.
If you use MacPorts, the following will get you set up:
sudo port install docbook-xml-4.5 docbook-xsl fop
If you use Homebrew, use this:
brew install docbook docbook-xsl fop
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 xmllint... xmllint checking for DocBook XML V4.5... yes checking for dbtoepub... dbtoepub checking for xsltproc... xsltproc checking for fop... fop
If xmllint was not found then some of the following
tests will be skipped.