Release Documentation

Orderless Tables sample

1. Contents of the sample files

The key part of the sample input files is the table. The first version has the rows of the table in code number order, 01 to 06. The second version has three changes: the order of the rows is shuffled to be alphabetical by product name, the row for code 06 has a price change, and a new row with code 07 has been added.

There are three pairs of input files that include differet processing instructions to control the table comparison.

  1. no-PIs. These files contain no PIs and the rows in the table will be compared in an 'ordered' manner. This results in a large number of row additions and deletions because of the re-ordering in version 2.

  2. with-PI. These files contain a processing instruction for dxml-orderless-rows in the table. This means that simple row re-ordering is not considered to be a change because the rows are compared in an 'orderless' manner. The result contains fewer row additions and deletions. Item 06 is still marked as a row deletion and addition because, by default, orderless items only match together when they are precisely the same. The next pair of inputs uses a 'key' instruction to improve the result.

  3. with-PI-and-key. These files include a keying instruction on the processing instruction so that it now reads <?dxml-orderless-rows cell-pos:1?>. This means that the text value in the first cell entry in each row is used as a 'key' to uniquely identify the row during comparison. This means that row 06 is now marked up with the price change rather than as added and deleted.

2. Running the sample via the Ant build script

If you have Apache Ant installed, use the build script provided to run the sample. This sample will work from the samples/OrderlessTables directory, by using the ant command.

The Ant command runs three comparisons, using each of the pairs of input files and producing three result files.

3. Running the sample from the Command-line

It is possible to compare two DocBook files using the command line tool from the samples/OrderlessTables directory as follows, where '\' is a line continuation character. The indent parameter at the end is used to make the result file more readable.

java -jar ../../deltaxml-docbook.jar compare \
                docbook-orderless-table-version-1-with-PI-and-key.xml \
                docbook-orderless-table-version-2-with-PI-and-key.xml \
                result-with-PI-and-key.xml indent=yes

The following line can be copied and pasted directly into the Terminal window, when set to the samples/OrderlessTables directory.

java -jar ../../deltaxml-docbook.jar compare docbook-orderless-table-version-1-with-PI-and-key.xml docbook-orderless-table-version-2-with-PI-and-key.xml result-with-PI-and-key.xml indent=yes

The result-with-PI-and-key.xml file contains the result.

Various parameters are available as discussed in the User Guide and summarised by the following command

java -jar ../../deltaxml-docbook.jar describe

4. Running the sample using a shell script

The shell script orderless.sh can be used to run all three samples.