AsciiDoc DocBook XSL Stylesheets Notes

All current AsciiDoc PDF and manpage documentation has been generated using DocBook XSL Stylesheets version 1.72.0, these notes and patches relate to this version. The version of FOP used is 0.20.5 (I did try FOP 0.93 under Ubuntu 6.10, but got a Java exception which I didn't pursue).

My tools of choice for converting AsciiDoc generated DocBook files to PDF and manpage files are xsltproc(1), FOP and DocBook XSL Stylesheets. Output file customisation is achieved by tweaking the DocBook XSL stylesheets. I've tried to keep customization to a minimum and confine it to the separate XSL driver files in the distribution ./docbook-xsl/ directory (see the User Guide for details).

To polish some rough edges I've written some patches for the DocBook XSL stylesheets — you don't need them but they're documented below and included in the distribution ./docbook-xsl/ directory.

Manually upgrading Debian to the latest DocBook XSL stylesheets

The DocBook XSL Stylesheets distribution is just a directory full of text files and you can switch between releases by changing the directory name in the system XML catalog.

To upgrade to the latest docbook-xsl stylesheets without having to wait for the Debian docbook-xsl package:

Download the latest docbook-xsl tarball from http://sourceforge.net/projects/docbook/.

Unzip the tarball to /usr/share/xml/docbook/stylesheet/:

$ cd /usr/share/xml/docbook/stylesheet
$ sudo tar -xzf /tmp/docbook-xsl-1.72.0.tar.gz

Edit /etc/xml/docbook-xsl.xml catalog and replace occurences of the current stylesheets directory with the new one (in our example it would be /usr/share/xml/docbook/stylesheet/docbook-xsl-1.72.0.
```
$ cd /etc/xml/
$ sudo cp -p docbook-xsl.xml docbook-xsl.xml.ORIG
$ sudo vi docbook-xsl.xml
```
Apply optional patches (see below).

Patches to DocBook XSL Stylesheets

You'll find the patch files in the AsciiDoc distribution archive ./docbook-xsl/ directory.

Shade Literal Block Patch

The processing expectation for AsciiDoc LiteralBlocks and LiteralParagraphs is that they are not shaded. The shaded-literallayout.patch was devised to allow AciiDoc Listing blocks to be shaded while leaving Literal paragraphs and Literal blocks unshaded (the default DocBook XSL Stylesheets behavior is to shade all verbatim elements).

The patch implements a shade.literallayout XSL parameter so that shading in literal elements could be disabled while other verbatim elements are left shaded (by setting the XSL shade.verbatim parameter).

The relevant patch file is shaded-literallayout.patch and it can be applied from the DocBook XSL Stylesheets directory:

$ cd /usr/share/xml/docbook/stylesheet/docbook-xsl-1.72.0
$ sudo patch -p0 < /tmp/shaded-literallayout.patch