Release Documentation

ReadMe

1. Introduction

Welcome to the DeltaXML DITA Compare product. DITA Compare highlights changes between two versions of a DITA document, such as minor changes between editing sessions or more significant changes between customer releases. Here, the document can either be a topic, a map file or a collection of topics (map topicset) as specified by a map (and its submaps).

The User Guide provides a high-level introduction to using the DITA compare product, while the Reference contains more detailed information, these documents are intended to supplement this ReadMe document. Additional help is provided by Samples demonstrating use of the API and specific map and topic comparison features. The Release Notes essentially contain a history of changes for the product, which includes changes to the API and a discussion on backwards compatibility issues.

2. 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 .jar 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-dita.lic.

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.

3. Using the 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 .Net objects (or IKVMed Java objects) as input/output types.

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

4. 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.

Its can be used in the following forms:
deltaxml-dita.exe license
deltaxml-dita.exe describe [topic|mts|mapfile]
deltaxml-dita.exe compare topic arguments
deltaxml-dita.exe compare mts arguments         
deltaxml-dita.exe compare mapfile arguments

The license command is used to display the license data that will be checked before running a comparison.

The describe command lists the parameters that can be used to configure the comparison. It can be supplied with an optional topic, mts or mapfile argument, which lists the parameters available for configuring these comparison types. Note that a mts comparison is an alias for 'maptopicset' (a Map Topicset Comparison) and makes use of the topic comparison, thus all the topic comparison parameters are also available for mts comparison.

The first argument of the compare command specifies the comparison type and the subsequent arguments specify the inputs, outputs, and optional parameters.

The compare command has a number of possible arguments. For the topic and mapfile comparison types it takes three file arguments, the two input files and a file location for the result.

deltaxml-dita.exe compare topic in1.xml in2.xml out.xml [param=value]*

When using the Map Topicset (mts) comparison type, the compare command takes three arguments which are used to specify the input maps, and either the output directory or inplace string, depending on whether an in place comparison is wanted. Further, when the comparison is provided with an output directory, this directory must not already exist; it is created as part of the comparison process.

deltaxml-dita.exe compare mts in1.xml in2.xml outDir [param=value]*
deltaxml-dita.exe compare mts in1.xml in2.xml inplace [param=value]*

The Configuring a Comparison section of the User Guide provides information on configuring the comparison via the optional parameters. Further details on these parameters can be found in the Parameters Appendix of the Reference document.

5. Configuration Properties and Catalog Support

General system configuration is managed through the setting of Configuration Properties. These Configuration properties complement the parameters by providing control over some of the non-comparison specific features.

The configuration property features include:
  • 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 .

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

5.1. Configuration Properties

Configuration properties can be set through both the API (via the 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-dita.dll 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" />

5.2. Configuring the catalogs

OASIS Catalogs can be used to locate entities (such as DTDs) and URIs. This section explains how to configure them.

If you wish to use additional catalogs that are searched before the built-in 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.exe 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\catalog1.xml" />

5.3. 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" />

6. JAR Files

The release contains a number of '.jar' files. This section lists them and also explains why/when they are required, which may be useful when considering deployment or redistribution.

deltaxml-dita.jar

This jar file contains the main DeltaXML DITA Compare API classes and associated resources (such as Java filters). It uses a manifest classpath containing: saxon9pe.jar xercesImpl.jar resolver.jar icu4j.jar flexlm.jar EccpressoAll.jar. These files should be present in the same directory for correct operation.

deltaxml-dita-gui.sh

This is the GUI client for running the comparsion on Unix based operating systems, including Linux and Mac OS X. It makes use of: deltaxml-dita-gui.jar, deltaxml-dita.jar, saxon9pe.jar, puremvc.jar and the relevant platform specific SWT .jar from swt-libs/ (the relevant JAR file is detected by the shell script). These files should be present in the same directory for correct operation.

deltaxml-dita-gui.jar

This jar file is required when using the GUI (invoked via ./deltaxml-dita-gui.sh).

puremvc.jar

This jar file is required when using the GUI (invoked via ./deltaxml-dita-gui.sh).

swt-libs/*.jar

The swt-lib/ folder contains platform specific SWT jar files, which are required when using the GUI (invoked via ./deltaxml-dita-gui.sh) and the correct one is auto detected.

resolver.jar

This modified version of the apache catalog resolver is needed when using catalogs (either through the deltaxml-dita.jar APIs or when using the or GUI clients. Classes from this file are invoked using reflection and it is therefore an optional jar and is only required if using catalog files. Please see Catalog Resolver Customizations for further details of the modifications we have made.

saxon9pe.jar

This jar file is required when using the dita packages and the client applications.

xercesImpl.jar

This file is required by the client applications and is recommended for use with the dita packages by including it on the classpath. Alternative SAX parsers can be used by using the classpath or the JAXP SAXParserFactory methods.

xml-apis.jar

This file is required by any applications which also make use of xercesImpl.jar version 2.11.0 or later. In previous releases, where Xerces-J version 2.9 was provided, this file was not required, and it was preferable to make use of the JAXP interfaces provided by the Java JDK/JRE. However, changes to the way in which Xerces is shipped means this jar file is now required at runtime (but not compile time, where the JDK is sufficient).

icu4j.jar

This jar file is required when using the com.deltaxml.pipe.filters.dx2.wbw.WordInfilter filter.

flexlm.jar, EccpressoAll.jar

These jar files are required for the Flexera based licensing capabilities introduced in the 6.5.3 and later releases. They should always be included on the classpath.

7. 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!

8. Updating your licence

The software licence file may need to be upgraded or replaced, such as when changing from an evaluation to full licence or renewing an annual subscription.

  1. Locate existing License.
    It is usually located in the 'bin' 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.
  2. Replace the existing license.
    The upgrading process is simply a matter of replacing the original licence file with an updated licence file.