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 variant of the DocBook DTD, but to build man pages you also need the XML variant of the same version.
These are required by DocBook 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.
This is another stylesheet for converting DocBook to other formats. We currently use this to produce man pages and optionally HTMLHelp. You can also use this toolchain to produce HTML or PDF output, but official PostgreSQL releases use the DSSSL stylesheets for that.
The minimum required version is currently 1.74.0.
This is the base package of SGML processing. It contains an SGML parser, a DSSSL processor (that is, a program to convert SGML to other formats using DSSSL stylesheets), as well as a number of related tools. Jade™ is now being maintained by the OpenJade group, no longer by James Clark.
This is the processing tool to use with the XSLT stylesheets (like jade is the processing tool for DSSSL stylesheets).
If you want to, you can also install JadeTeX™ to use TeX™ as a formatting backend for Jade™. JadeTeX can create PostScript or PDF files (the latter with bookmarks).
However, the output from JadeTeX is inferior to what you get from the RTF backend. Particular problem areas are tables and various artifacts of vertical and horizontal spacing. Also, there is no opportunity to manually polish the results.
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.
Most vendors provide a complete RPM set for DocBook processing in
their distribution. Look for an “SGML” option while
installing, or the following packages:
sgml-common
, docbook
,
stylesheets
, openjade
(or jade
). You may also need sgml-tools
and either xsltproc
or libxslt
. If your
distributor does not provide these then you should be able to make
use of the packages from some other, reasonably compatible vendor.
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/sp
textproc/openjade
textproc/iso8879
textproc/dsssl-docbook-modular
textproc/docbook-420
A number of things from /usr/ports/print
(tex
, jadetex
) might
also be of interest.
It's possible that the ports do not update the main catalog file
in /usr/local/share/sgml/catalog.ports
or that the
order isn't proper. Be sure to have the following lines in the beginning
of the file:
CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog"
If you do not want to edit the file you can also set the
environment variable SGML_CATALOG_FILES
to a
colon-separated list of catalog files (such as the one above).
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-dsssl docbook-xsl openjade1.3 opensp xsltproc
If you use MacPorts, the following will get you set up:
sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade 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 OpenJade offers a GNU-style
./configure; make; make install
build
process. Details can be found in the OpenJade source
distribution. In a nutshell:
./configure --enable-default-catalog=/usr/local/share/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 jade later on.
(This method is also an option if OpenJade is already
installed and you want to install the rest of the toolchain
locally.)
Some users have reported encountering a segmentation fault using OpenJade 1.4devel to build the PDFs, with a message like:
openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted make: *** [postgres-A4.tex-pdf] Segmentation fault
Downgrading to OpenJade 1.3 should get rid of this error.
Additionally, you should install the files
dsssl.dtd
, fot.dtd
,
style-sheet.dtd
, and
catalog
from the
dsssl
directory somewhere, perhaps into
/usr/local/share/sgml/dsssl
. It's
probably easiest to copy the entire directory:
cp -R dsssl /usr/local/share/sgml
Finally, create the file
/usr/local/share/sgml/catalog
and add
this line to it:
CATALOG "dsssl/catalog"
(This is a relative path reference to the file installed in Step 2. Be sure to adjust it if you chose your installation layout differently.)
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.)
To install the style sheets, unzip and untar the distribution and
move it to a suitable place, for example
/usr/local/share/sgml
. (The archive will
automatically create a subdirectory.)
$
gunzip docbook-dsssl-1.
xx
.tar.gz$
tar -C /usr/local/share/sgml -xf docbook-dsssl-1.
xx
.tar
The usual catalog entry in
/usr/local/share/sgml/catalog
can also be
made:
CATALOG "docbook-dsssl-1.xx
/catalog"
Because stylesheets change rather often, and it's sometimes beneficial to try out alternative versions, PostgreSQL™ doesn't use this catalog entry. See the section called “Detection by configure” for information about how to select the stylesheets instead.
To install and use JadeTeX™, you will need a working installation of TeX™ and LaTeX2e™, including the supported tools™ and graphics™ packages, Babel™, AMS fonts™ and AMS-LaTeX™, the PSNFSS™ extension and companion kit of “the 35 fonts”, the dvips™ program for generating PostScript™, the macro packages fancyhdr™, hyperref™, minitoc™, url™ and ot2enc™. All of these can be found on your friendly neighborhood CTAN site. The installation of the TeX base system is far beyond the scope of this introduction. Binary packages should be available for any system that can run TeX.
Before you can use JadeTeX with the PostgreSQL™ documentation sources, you will need to increase the size of TeX's internal data structures. Details on this can be found in the JadeTeX installation instructions.
Once that is finished you can install JadeTeX:
$
gunzip jadetex-
xxx
.tar.gz$
tar xf jadetex-
xxx
.tar$
cd jadetex
$
make install
$
mktexlsr
The last two need to be done as root
.
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 openjade... openjade
checking for DocBook V4.2... yes
checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular
checking for collateindex.pl... /usr/bin/collateindex.pl
checking for xsltproc... xsltproc
checking for osx... osx
If neither onsgmls
nor
nsgmls
were found then some of the following tests
will be skipped. nsgmls
is part of the Jade
package. You can pass the environment variables
JADE
and 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 Jade can find it, or you have
not set up the catalog files correctly. See the installation hints
above. The DocBook stylesheets are looked for in a number of
relatively standard places, but if you have them some other place
then you should set the environment variable
DOCBOOKSTYLE
to the location and rerun
configure
afterwards.