Guide to Sample XSL Filters

Introduction

The samples/xsl-filters directory included in the distribution contains a number of filters, written in XSLT. Each of these XSLT filters can be used to customize comparator behaviour. Many of these filters are used in application samples, also included in the distribution, for DocumentComparator and PipelinedComparatorS9.

For more information about using and developing filters please refer to the XML Compare samples:

XML Compare - Samples and Guides

XSLT resources

XSLT 3.0 version is supported by XML Compare. The most authoritative documentation can be found in the XSL Transformation 3.0 W3C Recommendation

Michael Kay's "XSLT 2.0 and XPath 2.0 Programmer's Reference (Programmer to Programmer)" published by Wiley is a good reference for XSLT developers. The 4th edition is recommended and its ISBN is: 0470192747.

Saxonica's documentation includes a useful succinct reference to XSLT 3.0 and XPath 3.1:

XSLT processor compatibility

We have tested these stylesheets using Saxon 9.8.0.12 and 9.9.0.2 from Saxonica.

The PipelinedComparatorS9 and DocumentComparator APIs, included in the XML Compare product, provides easy pipeline construction with these filters and the XML Compare Comparator. Alternatively. Prototyping with the command line is also possible with Saxon and other XSLT 3.0 compatible processors.

Output Format/Compatibilities

The output from the XML-to-HTML stylesheets should be HTML5 and use CSS stylesheets. We have tried to conform to appropriate W3 standards rather than use browser specific features, extensions or bug-work-arounds.

The goal of these transforms is to provide pretty-printed output. It is therefore necessary to view the output HTML on a fully-featured, CSS supporting, graphical browser.

We recommend recent browsers such as Firefox, Microsoft Edge, Safari or Opera for correct/bug-free rendering of the HTML/CSS.

Application Samples

Samples illustrating how these filters can be included in an XML comparison solution are available in Bitbucket. See here. Pipelines of filters for the samples are constructed using one of the following:

DXP (A configuration file for PipelinedComparator S9)
DCP (A configuration file for DocumentComparator)
Java API

Other Input Filters

Input filters provide a way to change the input files before they are compared. One basic reason to do this is to remove white space. Another is to add keys and indicate where elements are unordered.

Whitespace-processing filters

lexical-whitespace.xsl

This filter rationalizes the output from the LexicalPreservation filter when DTD or XML Schema information is available. The result is that 'mixed-content' attributes are added and, if 'PreserveIgnorableWhitespace' is set true, ignorable whitespace text nodes are wrapped in 'preserve:ignorable' elements.

whitespace-detection.xsl

This filter is designed as a pre-processor for the NormalizeSpace filter. As such, it complements the 'lexical-whitespace.xsl' filter above, but adds whitespace-related attributes if no XML Schema or DTD information is available.

schema-input-filter.xsl

Purpose: Adds keys and unordered attributes to an XML Schema (Rec) file so that the comparison does not depend on the order of element definitions, items within a choice etc. Note that the order of these items is not preserved, so for example annotation elements at the top level may be re-ordered.

Recommended output filter: Generate a full delta output and use dx2-deltaxml-folding-html.xsl or dx2-deltaxml-sbs-folding-html.xsl

svg-input-filter.xsl

Purpose: Adds keys and unordered attributes to an SVG file. This is presented as an example only and may be incomplete.

Recommended output filter: Generate a full delta output and use dx2-deltaxml-folding-html.xsl or dx2-deltaxml-sbs-folding-html.xsl

Other Output Filters

Output filters provide a way to convert the output delta files into HTML or to perform other transformations, e.g. to convert a full delta file into a file representing the merge of the two input files.

Because the DeltaXML delta file has the same look and feel as the input files, the XSL filters are often very simple and can be based on filters developed for the original files.

dx2-deltaxml-folding-html.xsl

Purpose: Transforms a full delta file (DeltaV2) including any lexical-preservation elements into HTML for display. This can show changes to the attributes, elements, processing-instructions and comments. XSLT parameters defined in the stylesheet can be used to customise the rendering. Please see the code comments for details on these.

dx2-deltaxml-sbs-folding-html.xsl

Purpose: Similar to dx2-deltaxml-folding-html.xsl but shows changes in a side-by-side view. With the 'A' document view on the left, and the 'B' document view on the right.

dx2-extract-version.xsl

Purpose: This stylesheet converts a full-context delta file, into one of either input files. The selection of which input file to extract is through an XSLT parameter.