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
a couple of 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://docbook.sourceforge.net/projects/xsl/[].
- Unzip the tarball to `/usr/share/xml/docbook/stylesheet/`:

  # cd /usr/share/xml/docbook/stylesheet
  # 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`.

- Apply optional patches (see below).


Patches to DocBook XSL Stylesheets
----------------------------------
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 with the following
command:

  # patch -p0 < shaded-literallayout.patch

Manpage spurious .sp patch
~~~~~~~~~~~~~~~~~~~~~~~~~~
IMPORTANT: Don't apply this patch. It was designed for docbook-xsl
1.69.1 (the previous version of docbook-xsl used with AsciiDoc) and
does not work with 1.72.0. I don't think it's necessary with
docbook-xsl 1.72.0.

Standalone `simpara` and some nested `title` DocBook elements generate
`.sp` groff markup without a preceding newline, the `manpage-sp.patch`
fixes this as well as stripping out extra blank lines generated by
some `.sp` markup elements.

The patch can be applied from the DocBook XSL Stylesheets directory
with the following command:

  # patch -p0 < manpage-sp.patch