6.2. Installing a new version of DocBook

Preparing Cogent Documentation :
	Chapter 6. Tools

Installing DocBook is relatively easy. Unfortunately, different versions have slightly different sets of elements, and even the same elements may behave differently from version to version. Some of these differences are not documented, although they can be found by reading the source code. (You can start by grepping for FUTURE USE in the current and archive directories.) The most challenging task when installing a new version of DocBook is to validate and edit all of our documents with the new DTD once the new installation is complete.

There are many things about DocBook that I don't know, and the whole environment is changing rapidly. Although these instructions are given in step-by-step format, additional procedures may be necessary to achieve a successful installation. Be prepared to use your imagination and problem-solving skills.

Download the SGML zip archive of DocBook from the DocBook Open Repository Project on the Sourceforge web site.
Move the archive file to the /usr/share/sgml/ directory.
Create a folder for contents of the archive file, move it to that folder, and unzip it with the unzip command, like this:
```
unzip docbkX.X.zip
```

6.2.1. Catalog files

The new installation will come with its own catalog file, probably named catalog. A catalog file tells the processor where to find resources such as the DTD, ISO entities, and the stylesheets. Generally speaking, catalog files are like look-up tables that tell the processor where the resources are on your system. For example, a typical line from a catalog file looks like this:

PUBLIC "-//OASIS//DTD DocBook V4.1//EN" "docbook.dtd"

This tells the processor that the official DocBook DTD, which is publicly identified as -//OASIS//DTD DocBook V4.1//EN, can be found in the file docbook.dtd on this system. Different systems might have the DTD in a different places, but as long as their catalog file points the processor to the right location, they will all be able to process a given document.

We use a master catalog file called CATALOG that tells the processor where all the necessary catalog files are. This file and its path are specified by the shell variable SGML_CATALOG_FILES. If you are processing documents on your machine, you'll have to assign this variable. In Linux, this is done by editing the ~/.bash_profle file to include this line:

SGML_CATALOG_FILE=/path/to/file/CATALOG

Once this variable is assigned, you don't have to change it. The contents of the CATALOG look like this:

OVERRIDE YES

CATALOG "/usr/share/sgml/OpenJade/catalog"
CATALOG "/usr/share/sgml/docbook/dtd/4.1/catalog"
CATALOG "/usr/share/sgml/docbook/stylesheet/dsssl/modular/catalog"
CATALOG "/usr/share/sgml/sgml-iso-entities-8879.1986/catalog"

The OVERRIDE YES instruction at the top tells the processor that we want these catalog entries to override the system defaults. The CATALOG key words tell the system to include all of the associated catalogs. This file can be edited as necessary to include other files.

6.2.2. Set up Emacs

Now you are ready to edit a test document to use the new version of the DTD, and then set up Emacs to read and store its version of the DTD by parsing the test document.

Open doc/o/testfile/main.sgml.
Change the DocBook version number in the first line to the new version number, and save the document.
In the doc/ directory, move the docbook.ced file to docbook.ced.xx where xx is the number of the version of DocBook you've been using up to now.
Open your .emacs file and comment out the line containing the word docbook.ced. Save the file and restart Emacs.
Go back to doc/o/testfile/main.sgml and validate the document. This runs the Emacs PSGML parser, which searches for the docbook.ced file. When it can't find one, it creates a new one, based on the new DTD.
Save the docbook.ced file by using the Emacs command sgml-save-dtd.
Uncomment the docbook.ced line in your .emacs file, save the file, and restart Emacs.
Edit the first line of each main.sgml file in doc/o/*/ so that it has the new DocBook version number.
Make up a copy of each piece of the documentation and check the results carefully.

When all documents are processed correctly, you have successfully installed DocBook. If you encounter any problems, check DocBook - The Definitive Guide.