| Chapter 3. Getting the tools working | ||
|---|---|---|
 | Part I. Setting up the tools |  |
| Chapter 3. Getting the tools working | ||
|---|---|---|
| | Part I. Setting up the tools | |
Table of Contents
The first step to using the DocBook XSL stylesheets is to get the processing tools installed, configured, and tested to make sure they are working. There are several components that need to be installed:
DocBook DTD
DocBook XSL stylesheets
XSLT processor
XSL-FO processor
This chapter provides the details for obtaining, installing, and executing the individual tools to process DocBook files.
You can avoid most of those details by installing one of the already-assembled packages of DocBook tools that are available for download. A good number of them are inventoried at the DocBook Wiki site at http://wiki.docbook.org/topic/DocBookPackages. There are RPM and Debian packages for Linux systems, Fink packages for Mac systems, and Cygwin and other packages for Windows systems. The packages include most or all of the components listed above, and usually a convenience script to help you get started. If one of those packages meets your needs, then go for it.
The disadvantage of such packages is that they may not keep up with the latest releases of all of the components. Each of the components follows its own development schedule, and it is hard for all of the package developers to quickly integrate each new release into a new package. Installing your own components lets you update the components individually whenever they become available. Even if you install one of the packages, the information in this chapter can help you update individual components when you need to.
For most XSL tools, pathnames on a Microsoft Windows system should be specified using the standard URI syntax. For example, a Windows pathname such as c:\xml\docbook-xsl should be entered as file:///C:/xml/docbook-xsl. If you have spaces in part of the path, they must be escaped as %20. So a pathname such as c:\xml\docbook xsl would be entered as file:///C:/xml/docbook%20xsl. Generally spaces in pathnames should be avoided where possible.
You can download the DocBook XML DTD from the OASIS website where it is maintained. Go to http://www.oasis-open.org/docbook/xml/ and select the current version of the DocBook XML DTD. As of this writing the current version is 4.5. From there you should be able to download the zip archive of the XML DTD. You do not want the SGML DTD. If you are considering using DTD version 5.0, then see Chapter 4, DocBook 5 tools.
If you prefer to use the package installation software on your operating system, the DocBook DTD is also available in some package formats. Check the DocBook Wiki packages page to see if there is a DTD package for your system. If you install from a package, you might want to note where the files install so you can refer to that path later.
The DocBook XML DTD consists of a main file
docbookx.dtd and several module files. You only
need to reference the main file, and it will pull in the other module
files to make up the complete DTD.
In general, your XML documents must identify the DTD they are
written against by means of a DOCTYPE declaration at the top of the file. The information in the DOCTYPE provides the processor with clues for finding the DTD files. It might contain a PUBLIC identifier, and either a local file reference, or a URL reference (that may still be resolved to a local file).
DocBook documents written to version 4.5 of the DocBook XML DTD might look like the following:
Linux example: <!DOCTYPE book SYSTEM "/usr/share/docbook-4.5/docbookx.dtd"> Windows example: <!DOCTYPE book SYSTEM "file:///C:/xml/docbook45/docbookx.dtd">
This is a simple direct reference to a specific file location on your machine. It will work if the main DTD file is at that location. The problem with a specific reference like this is that it is not flexible. If you move your XML file to another machine where the DTD is installed somewhere else, or if you move the DTD on your machine, then the connection is lost. Fixing it is not a big problem if you have just a few files, but if you have hundreds of XML files, it is a tedious chore. It's also unnecessary if you use catalog files.
It is possible to fetch the DocBook DTD over the web. The XML standard supports using URLs for DTD references. The advantage is that the DTD is always available, as long as a web connection is available. That makes the document very portable.
The DOCTYPE declaration for network DTD access looks like the following:
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
Most XSL processors know how to fetch the DTD over the web, including all the DTD file modules that it references. This is not recommended for a slow network or flaky network connection. Even with a fast connection, it is slower than a local filesystem access. The next section shows you how to use a catalog to combine local and network access.
With an XML catalog, you can have the best of both local and network access. The catalog lets you map the standard network URL to a local file. If the catalog processor finds the local file during processing, it will use it. Otherwise, it falls back to using the network URL. With this arrangement, you get the speed of local access with the reliability and portability of network access.
An XML catalog entry looks like the following:
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<group id="DocbookDTD" prefer="public">
<system
systemId="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
uri="file:///usr/share/xml/docbook45/docbookx.dtd"/>
</group>
</catalog>
When processed with a catalog-aware XSL processor, a DOCTYPE
reference to the URL http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd will be replaced with the uri attribute value /usr/share/xml/docbook45/docbookx.dtd if that file exists on the local system. If not, then the
URL is used through network access.
See Chapter 5, XML catalogs for complete information on XML catalogs.
You can achieve a similar mapping with an SGML catalog, which is an older technology using a simpler syntax. The following is an example of an SGML catalog that maps both the PUBLIC and SYSTEM identifiers to a local file:
PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" \
"/usr/share/xml/docbook45/docbookx.dtd"
SYSTEM "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" \
"/usr/share/xml/docbook45/docbookx.dtd"
The DocBook DTD defines the character entities that make it
easy to add special characters to your XML files. To enter a
copyright symbol, for example, it is easier to remember a name like © than the equivalent © Unicode entity.
Depending on the source for your DTD download, the files that define the
character entity names may not be included.
They are on the OASIS website under
http://www.oasis-open.org/docbook/xmlcharent/index.shtml.
Create a directory named ent in the directory
where the DocBook DTD files are, and extract the entity files into ent. The DTD will find them in
that location because it has references that look like "ent/iso-amsa.ent".
Validation is the act of checking your document against the element names and rules in the DTD. Most XSL processors will not automatically take the time to validate your document while it is converting it to HTML or XSL-FO. The processor will read a DOCTYPE declaration in your file and try to find the DTD, and will likely report an error if it cannot. If it does find the DTD, it will read and use an entity declarations in it. If you use any DocBook character entities, the processor must be able to find the DTD to resolve those entity references.
Since the XSL processor does not automatically validate your document, it is possible to process invalid but well-formed DocBook documents. But you do so at your own risk, because the DocBook stylesheets expect to be processing a valid document. Your output may not be what you expect if you do not follow the rules. You will have fewer mysterious problems if you validate your documents before processing them.
Some of the XSLT processors described in later sections include validation utilities. For example, xsltproc includes a program called xmllint that can validate an XML document using a command like the following:
xmllint --valid --noout document.xml
If you are looking for a Java-based validation tool, there is a XML validation tool hidden in the distribution of Xalan 2.4 or newer. The xalansamples.jar file that is located with the other Xalan jar files has a Validate utility. If you include the xalansamples.jar file in your Java CLASSPATH along with the other Xalan jar files, then you should be able to use this command:
java Validate document.xml| DocBook XSL: The Complete Guide - 4th Edition | PDF version available | Copyright © 2002-2007 Sagehill Enterprises |
| |  | |
| Portability considerations |  | Installing the DocBook stylesheets |