J.2. Tool Sets
The following tools are used to process the documentation. Some might be optional, as noted.
- DocBook DTD
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.
- ISO 8879 character entities
These are required by DocBook SGML but are distributed separately because they are maintained by ISO.
- DocBook XSL Stylesheets
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.
- OpenSP
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.
- Libxml2 for
xmllint This library and the
xmllinttool 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, thatxmllintmight need to be installed from a separate subpackage.- Libxslt for
xsltproc xsltprocis an XSLT processor, that is, a program to convert XML to other formats using XSLT stylesheets.- FOP
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.
J.2.1. Installation on Fedora, RHEL, and Derivatives
To install the required packages, use:
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
J.2.2. Installation on FreeBSD
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-sgmltextproc/docbook-xmltextproc/docbook-xsltextproc/dsssl-docbook-modulartextproc/libxslttextproc/foptextproc/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.
J.2.3. Debian Packages
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
J.2.4. macOS
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
J.2.5. Manual Installation from Source
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.
J.2.5.1. Installing OpenSP
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.)
J.2.5.2. Installing the DocBook DTD Kit
Obtain the DocBook V4.2 distribution.
Create the directory
/usr/local/share/sgml/docbook-4.2and 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.2Unpack 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.zipRun 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.)
J.2.6. Detection by 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.