Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Tree: 412b4636c8
Fetching contributors…

Cannot retrieve contributors at this time

97 lines (72 sloc) 3.904 kB
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[].
- 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`
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
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
Jump to Line
Something went wrong with that request. Please try again.