2.3. Building the documentation

We use the DocBook DTD, which is widely used; however, shrink-wrapped distributions of DocBook are few and far between, and getting it to work out of the box can be tricky. There are currently three supported ways of using DocBook: installing from sources yourself, various flavours of RPM installation, and installing binaries on Windows (with some care).

Instructions on installing and configuring the DocBook tools follow.

2.3.1. Installing the DocBook tools from RPMs

If you're using a system that can handle RedHat RPM packages, you can probably use the Cygnus DocBook tools, which is the most shrink-wrapped SGML suite that we could find. You need all the RPMs except for psgml (i.e. docbook, jade, jadetex, sgmlcommon and stylesheets). Note that most of these RPMs are architecture neutral, so are likely to be found in a noarch directory. The SuSE RPMs also work; the RedHat ones don't at the moment.

2.3.2. Installing from binaries on Windows

It's a good idea to use Norman Walsh's installation notes as a guide. You should get version 3.1 of DocBook, and note that his file test.sgm won't work, as it needs version 3.0. You should unpack Jade into \Jade, along with the entities, DocBook into \docbook, and the DocBook stylesheets into \docbook\stylesheets (so they actually end up in \docbook\stylesheets\docbook).

2.3.3. Installing the DocBook tools from source

2.3.3.1. Jade

Install OpenJade (Windows binaries are available as well as sources). If you want DVI, PS, or PDF then install JadeTeX from the dsssl subdirectory. (If you get the error:
! LaTeX Error: Unknown option implicit=false' for package hyperref'.
your version of hyperref is out of date; download it from CTAN (macros/latex/contrib/supported/hyperref), and make it, ensuring that you have first removed or renamed your old copy. If you start getting file not found errors when making the test for hyperref, you can abort at that point and proceed straight to make install, or enter them as ../filename.)

Make links from virtex to jadetex and pdfvirtex to pdfjadetex (otherwise DVI, PostScript and PDF output will not work). Copy dsssl/*.{dtd,dsl} and catalog to /usr/[local/]lib/sgml.

2.3.3.2. DocBook and the DocBook stylesheets

Get a Zip of DocBook and install the contents in /usr/[local/]/lib/sgml.

Get the DocBook stylesheets and install in /usr/[local/]lib/sgml/stylesheets (thereby creating a subdirectory docbook). For indexing, copy or link collateindex.pl from the DocBook stylesheets archive in bin into a directory on your PATH.

Download the ISO entities into /usr/[local/]lib/sgml.

2.3.4. Configuring the DocBook tools

You should either edit one of the CATALOG files in fptools/glafp-utils/docbook to suit your system, or set SGML_CATALOG_FILES to point to a valid catalog. SuSE systems should work out of the box. CATALOG.generic should work on most Unix systems when the files have been installed as per these instructions; CATALOG.cygnus is for systems with the Cygnus DocBook tools. CATALOG.windows is for Windows systems following the special instructions for that special OS. You may need to edit the paths so they match your system. The edited file should be called CATALOG, and placed in the same directory.

One day there will be properly-working DocBook distributions everywhere and the world will be a better and a quieter place, whose people will have more time for interesting things.

2.3.5. Remaining problems

If you install from source, you'll get a pile of warnings of the form
DTDDECL catalog entries are not supported
every time you build anything. These can safely be ignored, but if you find them tedious you can get rid of them by removing all the DTDDECL entries from docbook.cat.