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.5; you cannot use later or earlier versions. You need theXML variant of the DocBook DTD, not theSGML variant.
- 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.
- Libxml2 for
xmllint#This 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
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. It is needed only if you want to build the documentation in PDF format.
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.
J.2.1. Installation on Fedora, RHEL, and Derivatives#
To install the required packages, use:
yum install docbook-dtds docbook-style-xsl libxslt fop
J.2.2. Installation on FreeBSD#
To install the required packages withpkg, use:
pkg install docbook-xml docbook-xsl libxslt fop
When building the documentation from thedoc directory you'll need to usegmake, because the makefile provided is not suitable for FreeBSD'smake.
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-xml docbook-xsl libxml2-utils xsltproc fop
J.2.4. macOS#
If you use MacPorts, the following will get you set up:
sudo port install docbook-xml docbook-xsl-nons libxslt fop
If you use Homebrew, use this:
brew install docbook docbook-xsl libxslt fop
The Homebrew-supplied programs require the following environment variable to be set. For Intel based machines, use this:
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
On Apple Silicon based machines, use this:
export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
Without it,xsltproc will throw errors like this:
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtdpostgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"...
While it is possible to use the Apple-provided versions ofxmllint andxsltproc instead of those from MacPorts or Homebrew, you'll still need to install the DocBook DTD and stylesheets, and set up a catalog file that points to them.
J.2.5. 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 xmllint... xmllintchecking for xsltproc... xsltprocchecking for fop... fopchecking for dbtoepub... dbtoepub
Ifxmllint orxsltproc is not found, you will not be able to build any of the documentation.fop is only needed to build the documentation in PDF format.dbtoepub is only needed to build the documentation in EPUB format.
If necessary, you can tellconfigure where to find these programs, for example
./configure ... XMLLINT=/opt/local/bin/xmllint ...
If you prefer to buildPostgreSQL using Meson, instead runmeson setup as described inSection 17.4, and then seeSection J.4.