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 are design to improve the processing of a DocBook file produced by our DocBook pipeline compare-docbook.dxp. 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 RenderX changebar extensions.
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.72.0
)
or by creating a symbolic link (this is the preferred method). An example of this is shown below:
prompt$ cd /path/to/docbook-xsl-{version}
prompt$ ln -s /path/to/docbook-changes-{version}
/deltaxml-fo deltaxml-fo
The stylesheets will then be accessible from
/path/to/docbook-xsl-
{version}
/deltaxml-fo/
Once you have a DocBook comparison result (or in fact, any DocBook file with revisionflag
attributes), producing XSL-FO output with RenderX extensions is 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-{version}
/deltaxml-fo/changebars.xsl
The XSL-FO result can 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.rx.changebars
and use.text.colors
. If are using
an alternative renderer to XEP, 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.rx.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 the 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.