B.2. Tool Sets

The following tools are used to process the documentation. Some may be optional, as noted.

This is the definition of DocBook itself. We currently use version 3.1; you cannot use later or earlier versions. Note that there is also an XML version of DocBook -- do not use that.

ISO 8879 character entities

These are required by DocBook but are distributed separately because they are maintained by ISO.

OpenJade

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.

DocBook DSSSL Stylesheets

These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.

DocBook2X tools

This optional package is used to create man pages. It has a number of prerequisite packages of its own. Check the web site.

JadeTeX

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 may be some other packaged distributions for these tools. Please report package status to the docs mailing list and we will include that information here.

B.2.1. Linux RPM Installation

Many vendors provide a complete RPM set for DocBook processing in their distribution, which is usually based on the docbook-tools effort at Red Hat Software. Look for an "SGML" option while installing, or the following packages: sgml-common, docbook, stylesheets, openjade (or jade). Possibly sgml-tools will be needed as well. If your distributor does not provide these then you should be able to make use of the packages from some other, reasonably compatible vendor.

B.2.2. FreeBSD Installation

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/docbook-310
textproc/iso8879
textproc/dsssl-docbook-modular

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. Be sure to have the following line in there:

CATALOG "/usr/local/share/sgml/docbook/3.1/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.

B.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 jade
apt-get install docbook
apt-get install docbook-stylesheets

B.2.4. 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.

B.2.4.1. Installing OpenJade

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

B.2.4.2. Installing the DocBook DTD Kit

Obtain the DocBook V3.1 distribution.
Create the directory /usr/local/share/sgml/docbook31 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/docbook31
$ cd /usr/local/share/sgml/docbook31
```
Unpack the archive.
```
$ unzip -a ...../docbk31.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 "docbook31/docbook.cat"
```
Optionally, you can edit the file docbook.cat and comment out or remove the line containing DTDDECL. If you do not then you will get warnings from jade, but there is no further harm.
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/docbook31
$ 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.)

B.2.4.3. Installing the DocBook DSSSL Style Sheets

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 Section B.3 for information about how to select the stylesheets instead.

B.2.4.4. Installing JadeTeX

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.