Table of Contents
Welcome to 'DeltaXML DocBook Changes', a DocBook XSL customisation. These stylesheets extend the DocBook XSL stylesheets and improve the processing of revisionflags on DocBook elements; the stylesheets have been tested with the DocBook XSL versions: 1.74.0, 1.76.1 and 1.78.1
The stylesheets are designed to exploit change information included in a DocBook file produced by DeltaXML DocBook Compare. This DocBook file will have revisionflag attributes showing where changes have occurred between two DocBook inputs. The stylesheets provided here are a customisation layer that enhances the XSL-FO output produced by the standard DocBook XSL stylesheets to include support for change highlighting and changebars. Changebars were introduced in the XSL-FO 1.1 standard and are supported by a number of tools with the notable exception of Apache FOP.
We have tested this customisation with Apache FOP and RenderX's XEP versions 4.7 and 4.9 and Bob Stayton reports sucess with Antenna House's XSL Formatter v4.1.
Before you can use the customisation, it must first be linked to the standard DocBook XSL stylesheets. This can be achieved either by copying the
deltaxml-fo
directory into the DocBook XSL top-level directory (e.g. docbook-xsl-1.78.1
) or by creating a
symbolic link (this is the preferred method). An example of this is shown below for Unix and Windows:
prompt$ cd /path/to/docbook-xsl-{version}
prompt$ ln -s /path/to/docbook-changes-{version}
/deltaxml-fo deltaxml-fo
c:\> cd \path\to\docbook-xsl
c:\> mklink deltaxml-fo /j \path\to\docbook-changes-{version}
\deltaxml-fo
The stylesheets will then be accessible from /path/to/docbook-xsl-
{version}
/deltaxml-fo/
An additional directory is provided for users of the namespaced or -ns
releases of docbook-xsl
. In this case
copying the deltaxml-fo-ns
directory into the DocBook XSL NS top-level directory (e.g. docbook-xsl-ns-1.78.1
) or
by creating a symbolic link (as shown above).
Once you have a DocBook comparison result (or in fact, any DocBook file with revisionflag attributes), producing XSL-FO output is fairly simple. Using
an XSLT processor, specify the input XML, the XSL to use (changebars.xsl
) and the name of the output file. Here is an example using
Saxon:
java -jar /path/to/saxon.jar -o docbook-diff.fo docbook-diff-result.xml \
/path/to/docbook-xsl-ns-{version}
/deltaxml-fo-ns/changebars.xsl
The XSL-FO result could then be processed using RenderX, for example:
/path/to/XEP/xep -fo docbook-diff.fo -output docbook-diff.pdf
Alternatively, you could use XEP to perform the process in one command:
/path/to/XEP/xep -xml docbook-diff-result.xml \
-xsl /path/to/docbook-xsl-{version}
/deltaxml-fo/changebars.xsl \
-output docbook-diff.pdf
The customisation layer performs both inline textual styling and the addition of changebars to indicate the location of changes. Either of these
features can be enabled independently through the use of XSLT parameter settings. For further details see the comments in the
changebars.xsl
. The two parameters of interest are: use.changebars
and
use.text.colors
. If you are using a renderer which does not support XSL-FO 1.1 change-bars, for example Apache FOP, you should turn
off the production of changebars, for example:
java -jar /path/to/saxon.jar -o docbook-diff.fo docbook-diff-result.xml \
/path/to/docbook-xsl-{version}
/deltaxml-fo/changebars.xsl \
use.changebars=0
/path/to/ApacheFOP/fop.sh -fo docbook-diff.fo -pdf docbook-diff.pdf
If you have already produced you own customisation layer for DocBook XSL, you will want to include that as part of the process of producing XSL-FO.
Our customisation has been designed to make this process as easy as possible. Simply import your top-level customisation stylesheet at the appropriate
place in changebars.xsl
(as indicated by the comments) and then trigger the docbook processing as in the section
above.
To ensure that there are no conflicts between your customisation and the changes customisation layer, it is a good idea to produce pdfs from the test files and check that changes are still highlighted correctly. See our how-to for details on resolving conflicts.
While these customisations are not a supported product of DeltaXML, we still welcome feedback/suggestions/fixes in the hope that they can be improved and utilized as a resource for the wider docbook community. Please get in touch (email support@deltaxml.com) with us if you have any comments or suggestions.
The DeltaXML Team.