7.4. Using the LDP XSL stylesheets

When working with DocBook XML, the LDP uses a series of XSL[1] stylesheets to process documents into HTML. These stylesheets create output files using the XML toolset that are similar to those produced by the SGML tools using ldp.dsl.

At the current time, the LDP XSL stylesheets are still in development and may not have all the functionality found in ldp.dsl. Specifically, the XSL-FO stylesheet for creating print documents has not yet been created. If you need PDF or other print output, you will need to use the SGML toolset and ldp.dsl.

The major difference between using ldp.dsl and the XSL stylesheets is the way that the generation of multiple files is handled, i.e. the creation of a separate file for each chapter, section and appendix. With the SGML tools, such as jade or openjade, the tool itself was responsible for generating the separate files. Because of this, only a single file, ldp.dsl was necessary as a customization layer for the standard DocBook DSSSL stylesheets.

With the DocBook XSL stylesheets, generation of multiple files is controlled by the stylesheet. If you want to generate a single file, you call one stylesheet. If you want to generate multiple files, you call a different stylesheet. For that reason the LDP XSL stylesheet distribution is comprised of four files:

1. ldp-html.xsl - stylesheet called to generate a single file.

2. ldp-html-chunk.xsl[2] - stylesheet called to generate multiple files based on chapter, section and appendix elements.

3. ldp-html-common.xsl - stylesheet containing the actual XSLT transformations. It is called by the other two HTML stylesheets and is never directly called.

4. ldp-print.xsl - stylesheet for generation of XSL Formatting Objects for print output. (Currently this file is a placeholder and has not been customized.)

You can find the latest copy of the files at http://www.linuxdoc.org/authors/tools/ldp-xsl.zip.

Once you have the file, you may need to do some editing of the first few lines based on the location of your DocBook XSL files.

Unzip the files into a directory where you will call them. You will then need to modify the files for your local installtion of the DocBook XSL stylesheets from Norman Walsh.

First open up ldp-html.xsl and look for the following line:

<xsl:import href="/usr/share/sgml/docbook/docbook-xsl-1.44/html/docbook.xsl"/>

Modify that path if necessary to point to where you have the docbook.xsl stylesheet installed.

Next open up ldp-html-chunk.xsl and look for the line:

<xsl:import href="/usr/share/sgml/docbook/docbook-xsl-1.44/html/chunk.xsl"/>

Modify that path if necessary to point to where you have the chunk.xsl stylesheet installed.

With that complete, you can now generate HTML files. To generate a single HTML file from your DocBook XML file, use the command:

bash$  xsltproc -o outputfilename.xml /usr/lib/sgml/stylesheets/ldp-html.xsl filename.xml

This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately.

To generate a set of linked HTML pages, with a separate page for each <chapter>, <sect1> or <appendix> tag, use the following command:

bash$  xsltproc /usr/lib/sgml/stylesheets/ldp-html-chunk.xsl filename.xml

Note that you never directly call the stylesheet ldp-html-common.xsl. It is called by both of the other two stylesheets.

At the current time, the print stylesheet, ldp-print.xsl has not been developed and provides no additional functions or customizations to the standard DocBook XSL stylesheets.