Installing the DocBook stylesheets

Installing the DocBook stylesheets
	Chapter 3. Getting the tools working

The DocBook XSL stylesheets are a fairly large collection of files that can be downloaded as a collection from the DocBook SourceForge website where they are maintained. Go to http://docbook.sourceforge.net to reach the main project page. From there, select Files, and then scroll down to list of file archives. You'll generally want the latest stable version. Then download the archive and unpack it anywhere that's convenient.

If you prefer to use the package installation software on your operating system, the DocBook XSL stylesheets are also available in many package formats such as Debian and RPM. Check the DocBook Wiki packages page to see if there is an XSL 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.

If you are on a Linux system or Windows with Cygwin, and install from a package (not the zip file), then the package installation should run the included shell script named install.sh to create a file named /etc/xml/catalog that indicates where the stylesheet files were installed. This file is an XML catalog file that maps generic identifiers to specific locations on your system. By default, xsltproc will use that catalog file. See Chapter 5, XML catalogs for more information on catalogs. The file named INSTALL that is included in the stylesheet distribution provides more information about installation.

Once you install the stylesheet distribution, you'll see these core subdirectories.

Table 3.1. Stylesheet subdirectories

Subdirectory	Description
`common`	Shared stylesheet modules, including languages.
`doc`	Documentation for the stylesheets in browsable HTML.
`extensions`	Program files that extend XSL for particular processors.
`fo`	Stylesheet modules that produce XSL-FO output.
`html`	Stylesheet modules that produce HTML output.
`images`	Icons and other images used in the output.
`lib`	Stylesheet modules shared among many outputs.

There will be other directories containing documentation source in XML, stylesheet customizations for specialized output such as HTML Help, and other tool files. But if you ever need to copy just the basic set of files for running the stylesheets in their standard HTML or XSL-FO outputs, then these are the directories you will need (plus the VERSION file in the top-level directory).

The stylesheet distribution includes an INSTALL file. This is a Bash shell script that builds an XML catalog file using the xmlcatalog utility. It only works on systems with a Bash shell (not Windows unless it is under Cygwin), and it is not required for using the stylesheets. See Chapter 5, XML catalogs for more on setting up your own XML catalog file.

Note

You do not actually have to download the stylesheet files to use them. Most XSL processors, if given a URL instead of a filename, will fetch the stylesheet over the Internet. However, because the DocBook stylesheets are big and use many file modules, this process uses a lot of network bandwidth and greatly slows down the processing of your documents. But it can be used in a pinch when you are on a machine that does not have the stylesheets installed. For example:

xsltproc  \
   http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl \
   myfile.xml


Chapter 3. Getting the tools working		Installing an XSLT processor