Release Documentation

Getting Started with DeltaXML DITA Merge

1. Introduction

Welcome to the DeltaXML DITA Merge product. It allows you to easily manage the complexities that arise when multiple authors are working on the same document resulting in multiple changes needing to be merged.

2. What can DeltaXML DITA Merge do?

DeltaXML DITA Merge takes two or more DITA files and merges the changes that have been made, relative to their common ancestor, into a single DITA file. It aligns content, identifies potential conflicts and shows differences in the output.

A common use case is to merge two variants of a file and this case is handled in a specific way to provide easy access to a variety of useful types of output. These outputs include optional resolution of the complex three-way changes into a simpler two-way representation familiar to users of change tracking in document editors.

Changes detected by DeltaXML DITA Merge are then typically resolved in an external process using rule-based approaches or interactively in an authoring or reviewing tool. For more complex requirements with more than three input files, a simple rule-based resolver can be configured and run from within the merger. Again, different types of output can be produced depending on the intended use of the result.

See the samples (in the samples folder of the distribution) to see how DeltaXML DITA Merge can be run.

3. 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-merge.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.

4. DeltaXML DITA Merge API

The API provides a simple way to integrate merge into your existing DITA processing workflow or CMS. 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 Merge 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-merge.jar command arguments

5.1. Supported Commands

The following commands and arguments are supported:

license
Prints out the current activated license details.
merge

Runs a merge with the given ancestor files and two or more revision files. Each file needs to have a name which is used to identify the version in the generated DeltaV2 result. The example below will merge three revisions ('anna', 'ben' and 'chris') against the 'ancestor' version. The inputs referenced used in the example below are included in the release. Note: the command has been wrapped to aid readability.

java -jar deltaxml-dita-merge.jar merge
                                  ancestor samples/data/four-edits.xml
                                  anna samples/data/four-edits-anna.xml
                                  ben samples/data/four-edits-ben.xml
                                  chris samples/data/four-edits-chris.xml
                                  result.xml

Parameters

Optional command-line parameters can be added to the end of the command-line, these are used to set options for the merge process. The command-line syntax for parameters is: param=value, where param is the parameter name and value the parameter value. The supported parameters are listed below:

result-type

Specifies the type of post-processing applied to the merge result. The types available are:

deltav2the raw result with no post-processing.
analyzed-deltav2performs first-line analysis of the result and adds attributes to indicate types of change.
rule-processed-deltav2applies default rules to auto-resolve the simple change types 'add' and 'delete'.
simplified-deltav2a simplified form of the deltaV2 format
simplified-rule-processed-deltav2the simplified format with the simple change types 'add' and 'delete' auto-resolved.
doctype-preservation-mode

Controls how DOCTYPE declarations appear in the result. The available modes are:

remove-alwaysno doctypes appear in the result, irrespective of what's in the inputs.
preserve-when-unchangedif no changes then preserved, otherwise removed.
error-when-changedif changes signal error, otherwise preserved in result.
entity-reference-preservation-mode

Controls how general entity references appear in the result. The available modes are:

use-replacement-textEntity references are replaced with their 'replacement text' (which may actually include general XML such as text, attributes and elements).
preserve-referencesEntity references remain in the body of the XML content. Declarations in the internal subset will also be preserved where possible. If multiple declarations with different values are used in the inputs then multiple declarations may appear in the result.
preserve-references-encoded-formEntity references remain in the body of the XML content in encoded output format. Declarations in the internal subset will also be preserved where possible. If multiple declarations with different values are used in the inputs then multiple declarations may appear in the result.
word-by-word

Controls the granularity of text/PCDATA comparison, alignment and change reporting:

trueText is segmented into words (as described in Unicode Annex 29, Section 4), compared and results are then reported as this granularity.
falseText is compared and changes reported corresponding to the text/PCDATA structure found in the comparison inputs.
table-processing

Controls the table processing.

trueEnables the table processing.
falseDisables the table processing.
debug

Controls the generation of intermediate pipeline debug files.

trueIntermediate pipeline debug files are generated.
falseIntermediate pipeline debug files are not generated.
merge3

Runs a merge with the given ancestor file and two revision files to generate a three way merge. Each file needs to have a name which is used to identify the version in the generated result. The example below will merge two revisions ('anna' and 'ben') against the 'ancestor' version. The inputs referenced used in the example are included in the release. Note: the command has been wrapped to aid readability.

java -jar deltaxml-dita-merge.jar merge3
                                  ancestor samples/data/four-edits.xml
                                  anna samples/data/four-edits-anna.xml
                                  ben samples/data/four-edits-ben.xml
                                  result.xml

Parameters

The command 'merge3' supports all the parameters listed within merge command parameters section (above). In addition to that, a merge3 command supports result format and three additional result types. These are used in a same way as merge command parameters.

result-type

Specifies the type of post-processing applied to the merge result. The types available are:

three-way-oxygen-track-changesproduces a merge result with oXygen Author track change processing instructions.
all-changesperforms three to two-way simplification and shows as many changes as possible.
conflicting-changesperforms three to two-way simplification and shows conflicts for further resolution. Simple, non-conflicting adds, deletes and modifications are automatically resolved.
their-changesperforms three to two-way simplification and shows conflicts for further resolution. Additionally changes in the third input are displayed. Simple, non-conflicting, changes in the second input are automatically resolved. This is designed for merge scenarios where the third input corresponds to the 'remote' or other users (their) branch.
result-format

Specifies various result formats for some of the result types produced by the three way merge. It is only applicable when the 'result-type' is all-changes, conflicting-changes or their-changes. The formats available are:

xml-deltaproduces either a deltaV2 result or a simplified delta result.
oxygen-track-changesproduces a result format which is an XML file with processing instructions used in the accept/reject interface of the oXygen XML editor/author
dita-markupproduces DITA markup output containing rev and status attributes to identify change.

6. Catalog Support

The distribution includes the OASIS DTDs and Schema files for DITA 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.2 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-dita directory of this distribution. Copy these files into either the installation directory of deltaxml-dita-merge.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 fixedcom.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. JAR Files

This section lists the number of '.jar' files in the release. They should always be included on the classpath while executing merge.

deltaxml-dita-merge.jar
This jar file contains the main DeltaXML DITA Merge API classes and associated resources (such as Java filters).
deltaxml.jar
This jar file contains the main DeltaXML Core API classes and associated resources (such as Java filters).
resolver.jar
This modified version of the apache catalog resolver is needed when using catalogs through the deltaxml-dita-merge.jar API. Please see Catalog Resolver Customizations for further details of the modifications we have made.
flexlm.jar and EccpressoAll.jar
These jar files are required for the Flexera based licensing capabilities introduced in the DeltaXML DITA Merge 2.2 and later releases. They should always be included on the classpath.
saxon9pe.jar, xercesImpl.jar and icu4j.jar
These jar files are required by the client applications and are mandatory with merge packages by including them on the classpath.

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!

The DeltaXML Team.

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

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