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.

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.

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.

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:

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.)

Note: Some users have reported
encountering a segmentation fault using OpenJade
1.4devel to build the PDFs, with a message
like:

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.)

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 Section
J.2.6 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.

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:

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.