DeltaXML DITA Compare ReadMe

1. Introduction

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

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.

2. What can DeltaXML DITA Compare do?

DeltaXML DITA Compare compares two input DITA documents and generates an output DITA document marked up with rev attributes and/or status attributes to show how the document has changed.

2.1. Highlighting changed text in the published document

DeltaXML DITA Compare can be used to add 'rev' attributes to changed elements or text fragments. The values of the attribute are configurable using the command line parameters old-revision and new-revision. During publishing, the rev attribute values can trigger actions defined in a ditaval file to add text decoration and colouring to highlight the changes that have been made. The deltaxml.ditaval file in the samples folder is an example of such a file.

See the dita-topic-version-1.xml and dita-topic-version-2.xml files in the samples folder for more details.

3. Quick Start with the GUI

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

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

4. DITA Compare API

The API provides a simple way to integrate DeltaXML DITA Compare into your existing DITA 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.

5. Command-line interface

DeltaXML DITA 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-dita.jar command arguments

5.1. 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 e.g. java -jar deltaxml-dita.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.

6. Catalog Support

The distribution includes the OASIS DTDs and Schema files for DITA 1.1 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 or Schema files for DITA 1.1 but will use its local copy.

6.1. 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-dita.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

6.1.1. 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-dita.jar!/catalog.xml" />

7. Implementation Notes

7.1. 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 XPath2.0 book.

Table 1. Unicode private characters
Predefined XML Entity	Private Unicode Character
<	
&	
>	
'	
"	

8. Feedback

We are always keen to improve our products - please make use of our Support Forums if you have any comments or suggestions while working with DeltaXML. We hope you enjoy it!

9. 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 mater of replacing the original licence file with an updated licence file.

10. Licence Information and Notices

10.1. DeltaXML Licensing

The DeltaXML software is licenced under the terms described in the file Licence.html. The licence terms in this file differ depending upon whether this is an evaluation release of the software or a purchased release.

10.2. Third Party Notices Index

10.2.1. Saxon Licensing

Included in the distribution is the saxon9pe.jar, which is a binary component of the professional edition of Saxon ('The SAXON XSLT and XQuery Processor from Saxonica Limited.'). This version of Saxon may only be used when invoked from a DeltaXML product.

The home page for Saxonica is http://www.saxonica.com. For further details of Saxon's licensing please see http://www.saxonica.com/license/license.xml and the docs/notices/saxon/ subdirectory included in the DeltaXML DITA Compare distribution. In particular, the docs/notices/saxon/LEGAL.txt file describes how the license/notices of third party code included in Saxon is handled.

10.2.2. Apache Licensing

This product includes software developed by the Apache Software Foundation (http://www.apache.org), these include:

the xercesImpl.jar component from the binary 2.9.0 release of the Xerces-J SAX parser.
the DeltaXML variant of the resolver.jar component from the 1.2 release of the Apache Commons Resolver OASIS catalog reader.

The DeltaXML adaptation of Apache's resolver contains standard fixes for some of the known bugs and an enhancement that enables entities to be loaded via Java's resource loading mechanism. For further information please contact us.

These components are: Copyright (c) 1999-2006 The Apache Software Foundation. All rights reserved. and are licensed under the terms of the Apache License, Version 2.0. These components must be used under the terms of the license at: http://www.apache.org/licenses/LICENSE-2.0

In accordance with section 4(d) of the Apache License, the notices for these libraries are enclosed in appropriately labelled subdirectories of the DeltaXML DITA Compare distribution, as follows:

Xerces-J SAX parser notices are in the docs/notices/xerces/ directory.
Resolver catalog reader notices are in the docs/notices/resolver/ directory.

10.2.3. TrueLicense Licensing

The deltaxml-dita.jar file contains one compiled class from the 'TrueLicense Library', which is a component of the TrueLicense Library Collection. This code is: Copyright 2005 Schlichtherle IT Services, and licensed under the terms of the Apache License, Version 2.0.

In accordance with section 4(d) of the Apache License, the notices for these libraries are enclosed in the docs/notices/truelicense/ directory of the DeltaXML DITA Compare distribution.

10.2.4. OASIS DTD and Schema Licensing

Included in this distribution are unmodified copies of the OASIS DITA 1.1 DTDs (extracted from http://docs.oasis-open.org/dita/v1.1/OS/dtd/ditadtd.zip and Schema files (extracted from http://docs.oasis-open.org/dita/v1.1/OS/schema/ditaschema.zip). These are all 'Copyright OASIS Open' as stated at the start of each file.

10.2.5. DITA Open Toolkit Licensing

Included in this distribution are unmodified copies of generalize.xsl, specialize.xsl and dost.jar which are components of the DITA Open Toolkit.

In accordance with section 4(d) of the Apache License, the notices for these libraries are enclosed in docs/notices/dost/ directory of the DeltaXML DITA Compare distribution.

10.2.6. SWT Licensing

The Standard Widget Toolkit (SWT) has been used to construct the GUI components used in the release. One or more jar files may be included according to the specific platform release. These are licensed using the Eclipse Public License version 1.0 and a copy of the EPL is available at: http://www.eclipse.org/legal/epl-v10.html. The various SWT files also include third party content which may have different copyright and license terms. We have included the various about.html files with further details and the about_files directories with these notices as summarized below:

filename	license details	associated notices
`swt-lib/cocoa-macosx-x86.jar`	`docs/notices/swt/cocoa-macosx-x86/about.html`	`docs/notices/swt/cocoa-macosx-x86/about_files/`
`swt-lib/cocoa-macosx-x86_64.jar`	`docs/notices/swt/cocoa-macosx-x86_64/about.html`	`docs/notices/swt/cocoa-macosx-x86_64/about_files/`
`swt-lib/gtk-linux-x86.jar`	`docs/notices/swt/gtk-linux-x86/about.html`	`docs/notices/swt/gtk-linux-x86/about_files/`
`swt-lib/gtk-linux-x86_64.jar`	`docs/notices/swt/gtk-linux-x86_64/about.html`	`docs/notices/swt/gtk-linux-x86_64/about_files/`

10.2.7. PureMVC Licensing

Included in the distribution is a GUI which is built using the Java port of PureMVC. The PureMVC product and documentation is available from http://trac.puremvc.org/PureMVC_Java. For details of the PureMVC licensing please refer to the files within the docs/notices/puremvc/ directory of the DeltaXML DITA Compare distribution.

DeltaXML DITA Compare 4.1

Table of Contents