ReadMe

Introduction

Welcome to the DeltaXML DocBook Compare product. DeltaXML DocBook Compare enables you to compare two versions of a DocBook file against each other to produce a new DocBook file marked with revisionflag attributes where it has been changed. Alternatively, DocBook Compare can be configured to output the differences in some XML editor specific 'track change' formats, as discussed in the User Guide.

The DocBook markup output can then be processed further using our DocBook xsl customisation to produce HTML or XML-FO output that highlights added and deleted content and, in the case of XSL-FO, contains changebars. Further details here.

N.B. Only documents of the same type can be compared against each other, so a book can be compared against another book but not against an article or a chapter. Also, a DocBook 4 input cannot be compared against a DocBook 5 input that uses the new DocBook namespace.

The User Guide contains further information for the running of this tool. It does not replace this ReadMe document, but supports it by explaining: what data is preserved during the comparison (and why); how the comparison works; and what configuration parameters are available. The release notes essentially contain a history of changes to the tool, which includes changes to the API and a discussion on backwards compatibility issues.

License Setup

In addition to a product download (usually a ZIP file) you will also need to obtain a license file before you can run the software.

License files can be obtained either from our download and licensing subsite or by contacting DeltaXML support. The license file should then the placed either into the directory created by unpacking the product download (where you will find the product files) or into the home directory of the user(s) who will run the software. In either of these locations the software will attempt to locate the license file with the name: deltaxml-docbook.lic. Note that the product files will be .jar for a Java installation, .exe/.dll for .NET and an app for Apple.

The above procedure should allow the included developer applications and samples to run. More advanced forms of licensing are also supported including configuring the license using the product APIs and using concurrent or floating license servers. Please consult the licensing documentation for further details.

Quick Start with the GUI

The easiest way to access DeltaXML DocBook Compare is to use the GUI, a demonstration application providing a graphical interface to let you compare your own DocBook files. Select two files and the GUI will display the generated DocBook.

You can start the GUI by running deltaxml-docbook-gui.sh in your terminal.

DeltaXML DocBook Compare API

The API provides a simple way to integrate DeltaXML DocBook Compare into your existing DocBook processing workflow. It provides access to all of the parameters and allows the use of various combinations of Java Objects as input/output types.

See the API documentation for details on parameter settings and their effects.

Command-line interface

DeltaXML DocBook Compare can be run using a command-line interface that is invoked from a terminal window or Windows command line. It is used like this:

java -jar deltaxml-docbook.jar command arguments

Supported Commands

The following commands and arguments are supported:

license             Prints out the current activated license details.

describe         Lists the options available on the compare command.

compare         Compares two inputs to produce a result. Takes a minimum of three file arguments, the two input files and a location to output the result for example:

java -jar deltaxml-docbook.jar compare input1.xml input2.xml result.xml

There are a number of other optional arguments that can be used. For a full list, run the describe command.

Configuration Properties and Catalog Support

Configuration properties complement the parameters by providing control over some of the non-comparison specific features, such as:

• whether debug information should be produced;

• where the catalogs can be located; and

• whether the command line output should overwrite an existing output file without asking the user for permission.

A full list of configuration properties for this tool is contained in the Configuration Properties Appendix  of the User Guide.

The distribution includes the OASIS DTD, XML Schema and RelaxNG Schema for DocBook 4.3, 4.4, 4.5 and 5.0 as well as the Apache XML Commons Resolver to provide support for XML catalog use. This means, that out-of-the-box, the tool will not need to download the DTDs for these DocBook versions but will use its local copy.

Configuration Properties

Configuration properties can be set through both the API (via the com.deltaxml.docbook.ConfigProperties class) or a configuration file (deltaxmlConfig.xml). A sample configuration file (and dtd) is provided in the samples/config directory of this distribution.

A configuration property is constructed from a triple:

name     A string representing the name of the property.

value     A string representing the value of the property.

fixed     A boolean specifying whether this property can be overridden.

The configuration properties file is typically located in the same directory as the product's library (i.e. the directory that contains the deltaxml-docbook.jar file). We refer to this directory as the installation directory for the remainder of this discussion on configuration properties. If the file cannot be found in the installation directory then it is looked for in the user's home directory, and then the current working directory.

It is sometimes useful to be able to specify a property in terms of other properties. For example, it would be possible to specify a property P in terms of a property Q by including the text ${Q} in P's value. Note that Java system properties, such as user.home and user.dir can be referred to in this way (i.e. ${user.home} and ${user.dir} respectively). We also provide an install.dir property, for locating the product's installation directory, when this information is obtainable from the JVM. Some application servers prevent the automatic installation directory detection from working.

A DeltaXML configuration file can specify a 'search path list' to look for additional properties to be set (or overridden - if they have not previously been fixed). Here, the first search path in the list that exists is loaded; all other entries in the search path are ignored. Further, any attempt to reload a previously visited configuration file will finish the configuration file loading process.

Note that the configuration properties that are specified in configuration files, are loaded before any specified through the API.

For example the configuration property com.deltaxml.cmdline.forceOverwrite can be set to true as follows:

<configProperty name="com.deltaxml.cmdline.forceOverwrite" value="true" fixed="false" />

An alternative way of setting these properties for a single Java invocation only is to use a System property setting when invoking the java command. e.g.

-Dcom.deltaxml.cmdline.forceOverwrite=false

Configuring the catalogs

If you wish to use additional catalogs that are searched before the in-built catalog you need to supply the location(s) using a deltaxmlConfig.xml file. A sample file (and dtd) is provided in the samples/config directory of this distribution. Copy these files into either the installation directory of deltaxml-docbook.jar file or into your user home directory and then modify the value of com.deltaxml.ext.catalog.files to the relevant path(s). For example:

<configProperty name="com.deltaxml.ext.catalog.files"
                     value="C:\catalogs\my_catalog.xml;C:\another-catalog.xml" />

If you wish to completely override the built-in catalog, set the xml.catalog.files property instead.

Please note, it is also possible to use the built-in catalog first, and then additional catalogs by using the fixed com.deltaxml.rsc.catalog.files property within the definition of the xml.catalog.files property as follows:

<configProperty name="xml.catalog.files" 
                     value="${com.deltaxml.rsc.catalog.files};C:\catalogs\my_catalog.xml" />

An alternative way of setting these properties for a single Java invocation only is to use a System property setting when invoking the java command. e.g.

-Dcom.deltaxml.ext.catalog.files.catalog.files=C:\catalogs\my_catalog.xml;C:\another-catalog.xml

Catalog Support in an Application Server

Some application servers use classloaders that, for security reasons, limit the ability to dynamically access some resources and access the location of the running code. If this is the case, you will need to set the xml.catalog.files variable even if you wish to use the inbuilt dtds. It should be set to the following, with the relevant path:

<configProperty name="xml.catalog.files"
                      value="jar:file:/path/to/install/directory/deltaxml-docbook.jar!/catalog.xml" />

Implementation Notes

Private use characters

The Unicode Character Set includes many code points for private use, which are recognised as legitimate Unicode character codes, but are not provided with an (abstract) character. Instead, they are intended to be used within closed systems as the user or developer sees fit. For further details please refer to either the Unicode standard or the Wikipedia entry on Unicode's private use characters.

This product internally uses five characters from the Unicode private character set to represent the values of the predefined XML entities, as illustrated by the following table. For those with a background in XSLT processing, we are following Michael Kay's XSLT-2 'Character Maps as a Substitute for disable-output-escaping' scheme, from the 4th edition of his Programmer's Reference to XSLT 2.0 and XPath 2.0 book.

Feedback

We are always keen to improve our products - please contact us if you have any comments or suggestions while working with DeltaXML. We hope you enjoy it!

Updating Your Licence

The licence file may need to be upgraded or replaced, such as when changing from an evaluation to full licence or renewing an annual subscription. It is usually located in the top-level directory of the installation. However, it can also be located in a user's home directory, though in this case the licence will only be available to the user whose home directory the licence file is in. The upgrading process is simply a matter of replacing the original licence file with an updated licence file.

Licensing and Legal Notices

The DeltaXML software is licensed under the terms described in the file Licence.html. The software also includes components developed by others, the redistribution and copyright terms, including necessary notices are described in docs/legal-notices.html.