AsciiDoc DocBook XSL Stylesheets Notes
======================================

PDF generation from AsciiDoc generated DocBook using FOP plus DocBook XSL
Stylesheets.

- FOP 0.95beta.
- DocBook XSL Stylesheets version 1.72.0.

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
----------------------------------
NOTE: 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
