Getting Started

 Table of Contents

Introduction

Welcome to DITA Compare.

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. Additional help is provided by Code Samples demonstrating use of the API and specific map and topic comparison features. The Release Notes contain a history of changes for the product, 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-dita.lic.

The product files will have extension .jar, .exe/.dll or .app depending on your platform.

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 for Java with the GUI

The easiest way to access 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.

This GUI is useful for trying out and demonstrating the capabilities of DITA Compare, but it is not intended as an everyday productivity tool.

Using the Java API

The API provides a simple way to integrate 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.

Command-line interface

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, depending on your platform:

Java
java -jar deltaxml-dita.jar license
java -jar deltaxml-dita.jar describe [topic|mts|mapfile]
java -jar deltaxml-dita.jar compare topic [arguments]
java -jar deltaxml-dita.jar compare mts [arguments]
java -jar deltaxml-dita.jar compare mapfile [arguments]
.NET
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.

Java
java -jar deltaxml-dita.jar compare topic in1.xml in2.xml out.xml [param=value]*
.NET
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.

Java
java -jar deltaxml-dita.jar compare mts in1.xml in2.xml outDir [param=value]*
java -jar deltaxml-dita.jar compare mts in1.xml in2.xml inplace [param=value]*
.NET
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.

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 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.shThis is the GUI client for running comparisons on Unix based operating systems, including Linux and macOS. 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.jarThis JAR file is required when using the GUI (invoked via ./deltaxml-dita-gui.sh).
puremvc.jarThis JAR file is required when using the GUI (invoked via ./deltaxml-dita-gui.sh).
swt-libs/*.jarThe 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.jarThis 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.jarThis JAR file is required when using the DITA packages and the client applications.
xercesImpl.jarThis 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.jarThis 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.jarThis jar file is required when Word by Word is enabled.
flexlm.jar, EccpressoAll.jarThese 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.

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 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.
  2. Replace the existing license.
    The upgrading process is simply a matter of replacing the original licence file with an updated licence file.
#content .code