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:

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.