DeltaXML Docbook Changes

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.