mirror of https://github.com/edeproject/ede.git
85 lines
3.4 KiB
Plaintext
85 lines
3.4 KiB
Plaintext
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
|