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.
These are required by DocBook but are distributed separately because they are maintained by ISO.
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.
These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.
This optional package is used to create man pages. It has a number of prerequisite packages of its own. Check the web site.
If you want to, you can also install JadeTeX to use TeX as a formatting backend for Jade. This will generate printed output that is inferior to what you get from the RTF backend. Tables are a particular problem area. Also, there is no opportunity to manually polish the results. Still, it works all right, especially for simpler documents that don't use tables, and as both JadeTeX and the style sheets are under continuous improvement, it will certainly get better over time.
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.
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 large, 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/docbook-310
textproc/iso8879
textproc/dsssl-docbook-modular
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.
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
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 reasonabley 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 installBe 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.
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. (Or just copy the entire directory.)
Obtain the DocBook V3.1 distribution.
Unpack the archive.
$ unzip -a docbk31.zip
Place the files into the directory /usr/local/share/sgml/docbook31. (The exact location is irrelevant, but this one is fairly standard.)
Create a 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.
To install the style sheets, simply unzip the distribution kit in a suitable place, for example /usr/local/share/sgml/stylesheets. (The archive will automatically create a docbook subdirectory.)
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, and of course JadeTeX itself. All of these can be found on your friendly neighborhood CTAN site.
JadeTeX does not at the time of writing come with much of an installation guide, but there is a makefile that shows what is needed. It also includes a directory cooked, wherein you'll find some of the macro packages it needs, but not all, and not complete -- at least last we looked.
Before building the jadetex.fmt format file, you'll probably want to edit the jadetex.ltx file, to change the configuration of Babel to suit your locality. The line to change looks something like
\RequirePackage[german,french,english]{babel}[1997/01/23]
and you should obviously list only the languages you actually
need, and have configured Babel
for.
It is quite likely that when you use JadeTeX with PostgreSQL documentation sources, that TeX will stop during the second run, and tell you that its capacity has been exceeded. This is, as far as we can tell, because of the way JadeTeX generates cross referencing information. TeX can, of course, be compiled with larger data structure sizes. The details of this will vary according to your installation.