Getting Started

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.

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.