Appendix A. Installation
- Table of Contents
- A.1. Installing the DocBook DTD
- A.2. Installing Jade
- A.3. Installing the ModularDocBook Stylesheets
A.1. Installing the DocBook DTD
This appendix describes how to install the DocBook DTD on your system so that popular command-line tools like SP can use it. If you are installing DocBook for use with a commercial application, consult the documentation for your application as well.
This appendix describes the installation of DocBook V3.1. If you are using another distribution, the process should be about the same, but there may be minor differences. DocBook V3.1 is backward compatible with DocBook V3.0, and is the recommended distribution at the time of this writing.
A.1.1. Unpacking the DocBook V3.1 Distribution
DocBook is distributed on the DocBook web site. You will also find a copy of the distribution on the CD-ROM.
The distribution consists of 14 files:
| 31chg.txt | Describes the changes in DocBook V3.1 from the preceding version (3.0) |
| 40issues.txt | Summarizes backwards-incompatible changes planned for DocBook V4.0 |
| 50issues.txt | Summarizes backwards-incompatible changes planned for DocBook V5.0 |
| cals-tbl.dtd | The CALS Table Model DTD |
| ChangeLog | A GNU-style ChangeLog summarizing the individual edits made on each file in the distribution since V3.0. |
| dbcent.mod | The character entity module |
| dbgenent.mod | The general entity module |
| dbhier.mod | The document hierarchy module |
| dbnotn.mod | The notations module |
| dbpool.mod | The information pool module |
| docbook.cat | A sample OASIS catalog for DocBook |
| docbook.dcl | An SGML Declaration suitable for DocBook |
| docbook.dtd | The DocBook DTD |
| readme.txt | The DocBook V3.1 "readme" file |
Unpack the distribution into a directory on your system. The exact location is irrelevant. On UNIX systems it's common to put it somewhere under /usr/local or /share (for example, /usr/local/sgml/docbook or /share/sgml/docbook). On a PC, perhaps c:\sgml\docbook.
A.1.2. Getting the ISO Entity Sets
DocBook refers to a number of standard entity sets that are not distributed with DocBook. (They aren't distributed with DocBook because they aren't maintained by the DocBook TC. They're maintained by ISO.) If you've installed other SGML DTDs or tools, they may already be on your system.
If you are missing some of them, they are available from Robin Cover's pages at OASIS: https://www.oasis-open.org/cover/ISOEnts.zip.[1] See https://www.oasis-open.org/cover/topics.html#entities for more information.
A.1.3. The DocBook Catalog
DocBook uses public identifiers to refer to its constituent parts. In some sense, DocBook is DocBook because it has the formal public identifier "-//OASIS//DTD DocBook V3.1//EN". In order for tools on your system to find your locally installed copy of DocBook, you must map these public identifiers into system identifiers, i.e., filenames, on your system. For a complete discussion of catalog files, see Section 2.3.
The DocBook distribution includes a sample catalog, docbook.cat, which provides a mapping for all of the public identifiers referenced by DocBook. This mapping won't work "out of the box" for two reasons: first, your tools won't be able to find it, and second, the mappings for the ISO entity sets probably don't point to the right place on your system.
A.1.3.1. Finding the Catalog
If you've already got some other SGML DTDs installed, you probably already have a catalog file. In this case, the easiest thing to do is append the DocBook catalog entries to the end of your existing catalog and then change them to point to the files on your system.
If DocBook is the first DTD that you're installing, make a copy of docbook.cat and call it catalog. Put this file in a higher-level directory and edit the relative pathnames that it contains to point to the actual locations of the files on your system. For example, if you installed DocBook in /share/sgml/docbk30/, put the catalog in /share/sgml/.
In order for applications to find your catalog file(s), you may have to change the application preferences or set an environment variable. For SP and Jade, set the environment variable SGML_CATALOG_FILES to the delimited list of catalog filenames. On my system, this looks like:
SGML_CATALOG_FILES=./catalog;n:/share/sgml/catalog;n:/adept80/doctypes/catalog.jade;j:/jade/catalog
(On a UNIX machine, use colons instead of semicolons to delimit the filenames.)
If you don't wish to set the environment variable, you can explicitly pass the name of each catalog to the SP application with the -c option, like this:
nsgmls -c ./catalog -c n:/share/sgml/catalog -c othercatalogs ...
A.1.3.2. Fixing the Catalog
The basic format of each entry in the DocBook catalog is:
PUBLIC "some public id" "some filename"
What you have to do is change each of the "some filenames" to point to the actual name of the file on your system.
 | Filenames should be supplied using absolute filenames, or paths relative to the location of the catalog file. |
To continue with the example above, let's say that you've got:
DocBook in /share/sgml/docbk30/,
The ISO entities in /share/sgml/entities/8879/, and
Your catalog in /share/sgml/catalog
Then you would change the catalog entry for the DTD to be:
PUBLIC "-//OASIS//DTD DocBook V3.1//EN" "docbk30/docbook.dtd"
You would change the catalog entry for the general technical character entities to:
PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN" "entities/8879/iso-tech.gml"
And similarly for the other public identifiers used by DocBook. In each case, the filename specified for the public identifier should be the name of the file on your system, specified as an absolute filename, or relative to the location of the catalog in which it occurs.
A.1.3.3. Mapping System Identifiers for XML
Since XML documents are required to have system identifiers, but are not required to have public identifiers, it's likely that some of the documents you want to process will only have system identifiers.
It turns out that you can still take advantage of the catalog in this case. The SYSTEM directive allows you to map the system identifier used in the document to the actual location on your system.
Suppose that you work with a colleague who uses the system identifier "file:///c:/sgml/db3xml/db3xml.dtd" to identify the XML version of DocBook on her system. On your system, you want to map that to "/share/sgml/db3xml/db3xml.dtd". The following entry in your catalog will do the trick:
SYSTEM "https://docbook.org/docbook/xml/1.4/db3xml.dtd" "/share/sgml/db3xml/db3xml.dtd"
Unfortunately, this technique only works with applications that read and understand catalog files.
A.1.4. Testing Your Installation
The best way to test your installation is with a simple command-line parser like nsgmls from SP. Create a small test document, like this:
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> <chapter><title>Test Chapter</title> <para> This is a test document. </para> </chapter>
and run the following command:
nsgmls -sv test.sgm
If the nsgmls command produces errors, review your catalog and resolve the errors. You can ignore warnings about DTDDECL being unsupported. It is unsupported, and there's no way to disable the warning message. Note, however, that this may also affect which SGML declaration gets used. When in doubt, pass the correct declaration explicitly and see if that corrects any problems. (To parse test.sgm with the declaration docbook.dcl explicitly, run nsgmls -sv docbook.dcl test.sgm.)
For some suggestions about how to work around these problems in SP and Jade, see the next section, Section A.2.
A.2. Installing Jade
For simplicity, the instructions assume that you are working with Jade on a Microsoft Windows machine. These instructions should be just as useful if you are working on another platform, except for the normal cross-platform idiosyncracies (path and filename separator characters, use of drive letters, etc.).
Download and unpack the Jade distribution. Binary distributions are available for some platforms, which makes installation a simple matter of unpacking the distribution. Or you can build Jade from the source (consult the documentation that comes with Jade for more detail about building it from source).
You may wish to add the directory where you installed Jade to your PATH. If not, make sure that you use the fully qualified name of the executable when you run the commands below.
A.2.1. Setting Up the Catalog
First, the catalog needs to be set up as described in Section A.1.3 in order for Jade to be able to parse your DocBook documents. In addition, Jade comes with its own catalog file that you must add to the SGML_CATALOG_FILES environment variable or otherwise make available to Jade.
A.2.2. Testing Jade
Download jtest.sgm and jtest.dsl. (Or get them off the CD-ROM in FIXME.) These are self-contained test documents. Test Jade by running:
jade -t rtf -d jtest.dsl jtest.sgm
This command should silently produce jtest.rtf. If you encounter warnings or errors here, Jade is not installed correctly. One possible culprit is your catalog setup. See Section 4.5.
A.2.2.1. DTDDECL Warnings
One annoying shortcoming in Jade is that it does not support the DTDDECL catalog directive and it complains loudly if it encounters one. In Jade, it's almost always possible to work around the problems that DTDDECL would solve, so you can generally ignore the warnings.
If you also use applications that do understand DTDDECL, and find the warnings too distracting to bear, setup alternate catalogs for SP applications, catalog.jade, that are identical to your normal catalogs but do not contain any DTDDECL entries. You can then avoid the warnings by putting catalog.jade in your SGML_CATALOG_FILES path, instead of catalog.
A.3. Installing the ModularDocBook Stylesheets
Norman Walsh (one of your intrepid authors ;-) maintains two DSSSL stylesheets for DocBook, one for print and one for online (HTML) output. You can obtain both of these stylesheets from https://nwalsh.com/docbook/dsssl/. (A recent version is also on the CD-ROM.)
If you have not already done so, download and install the DocBook DTD as described in Section A.1.
Likewise, if Jade is not installed on your system, download and install it as described in Section A.2.
Download and unpack the stylesheet distribution.
Test the installation by processing test.sgm (from the previous section) with Jade:
jade -t rtf -d d:\where-you-unpacked-the-stylesheets\docbook\print\docbook.dsl test.sgm
This command should silently produce test.rtf. If not, and the preceding test succeeded, something has gone wrong--contact the maintainer.
To test the HTML stylesheet, run:
jade -t sgml -d d:\where-you-unpacked-the-stylesheets\docbook\html\docbook.dsl test.sgm
This command should silently produce c01.htm. If not, and the preceding test succeeded, something has gone wrong--contact the maintainer.>