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 theSGML and theXML 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 asHTML.
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 ofSGML processing. Note that we no longer need OpenJade, theDSSSL processor, only the OpenSP package for converting SGML to XML.
- Libxml2 for
xmllintThis library and the
xmllinttool it contains are used for processing XML. Many developers will already haveLibxml2 installed, because it is also used when building the PostgreSQL code. Note, however, thatxmllintmight need to be installed from a separate subpackage.- Libxslt for
xsltprocxsltprocis 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 forxmllint andxsltproc 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 withpkg, use:
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
When building the documentation from thedoc directory you'll need to usegmake, because the makefile provided is not suitable for FreeBSD'smake.
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 forDebian 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 readSGML introductory material. The installation of OpenSP offers a GNU-style 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 Obtain the DocBook V4.2 distribution. Create the directory Unpack the archive: (The archive will unpack its files into the current directory.) Edit the file Download the ISO 8879 character entities archive, unpack it, and put the files in the same directory you put the DocBook files in: Run the following command in the directory with the DocBook and ISO files: (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.5.1. Installing OpenSP
./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/catalogmakemake install
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 theDocBookDTD Kit
/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$unzip -a ...../docbook-4.2.zip/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"
$cd /usr/local/share/sgml/docbook-4.2$unzip ...../ISOEnts.zipperl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
J.2.6. Detection byconfigure
Before you can build the documentation you need to run theconfigure script as you would when building thePostgreSQL programs themselves. Check the output near the end of the run, it should look something like this:
checking for onsgmls... onsgmlschecking for DocBook V4.2... yeschecking for dbtoepub... dbtoepubchecking for xmllint... xmllintchecking for xsltproc... xsltprocchecking for osx... osxchecking for fop... fop If neitheronsgmls nornsgmls were found then some of the following tests will be skipped.nsgmls is part of the OpenSP package. You can pass the environment variableNSGMLS 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.