Welcome to the DeltaXML 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 or monitored.
DeltaXML Merge takes two or more files and merges the changes that have been made into a single file. It aligns content, identifies potential conflicts and shows differences in the output.
There are two broad scenarios. A concurrent merge is used when there is one ancestor document that has been amended by a number of editors concurrently. Sequential merge is useful in a scenario in which each of the versions is a derivative of the previous version.
A common use case for DeltaXML Merge is to merge two variants of a file. A variety of output types are provided to support this case. 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 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 within the merge process. Again, different types of output can be produced depending on the intended use of the result.
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:
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.
The Java API provides a simple way to integrate merge into your existing 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.
DeltaXML 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-merge.jar command arguments
The following table describes the different types of merges. The merge type is used with the merge and describe commands.
Table 1. Table of Merge Types
|concurrent||N-Way concurrent merge|
|concurrent3||Three way concurrent merge|
|sequential||N-Way sequential merge|
The following commands and arguments are supported:
This command is used to see the description of the available parameters for the specified merge type.
java -jar deltaxml-merge.jar describe merge-type
java -jar deltaxml-merge.jar describe concurrent
Runs a merge for the specified merge type. Each file needs to have a name which is used to identify the version in the generated DeltaV2 result.
java -jar deltaxml-merge.jar merge merge-type ancestorName/version1Name ancestorFile/version1File (versionName versionFile)+ resultFile params
The example below will merge three revisions ('anna', 'ben' and 'chris') against the 'ancestor' version eith merge type as concurrent. The inputs used in the example below are included in the release. Note: the command has been wrapped to aid readability.
java -jar deltaxml-merge.jar merge concurrent ancestor samples/html-data/four-edits.html anna samples/html-data/four-edits-anna.html ben samples/html-data/four-edits-ben.html chris samples/html-data/four-edits-chris.html result.xml
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 is the parameter name and
value the parameter value. The supported
parameters are listed below:
Specifies the type of post-processing applied to the merge result. The types available are:
Table 2. Table of Result Types
|Result Type||Description||Merge Type|
|the raw result with no post-processing.||✓||✓||✓|
|performs first-line analysis of the result and adds attributes to indicate types of change||✓||✓||✓|
|applies default rules to auto-resolve the simple change types 'add' and 'delete'.||✓||✓|
|a simplified form of the deltaV2 format||✓||✓||✓|
|the simplified format with the simple change types 'add' and 'delete' auto-resolved.||✓||✓|
Controls how DOCTYPE declarations appear in the result. The available modes are:
|no doctypes appear in the result, irrespective of what's in the inputs.|
|if no changes then preserved, otherwise removed.|
|if changes signal error, otherwise preserved in result.|
Controls how general entity references appear in the result. The available modes are:
|Entity references are replaced with their 'replacement text' (which may actually include general XML such as text, attributes and elements).|
|Entity 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.|
|Entity 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.|
Controls the granularity of text/PCDATA comparison, alignment and change reporting:
|Text is segmented into words (as described in Unicode Annex 29, Section 4), compared and results are then reported as this granularity.|
|Text is compared and changes reported corresponding to the text/PCDATA structure found in the comparison inputs.|
Sets whether elements containing significantly modified text should be split.
|Enable element splitting when word-by-word is true and the amount of unchanged text in an element falls below 10%.|
|Disable element splitting.|
Controls the table processing.
|Enables the table processing.|
|Disables the table processing.|
Controls the generation of intermediate pipeline debug files.
|Intermediate pipeline debug files are generated.|
|Intermediate pipeline debug files are not generated.|
The command 'merge' with merge type 'concurrent3' supports all the parameters listed within the section 5.3. In addition to that, a command 'merge' with merge type 'concurrent3' supports result format and three additional result types. These are used in a same way as the merge command parameters.
Specifies the type of post-processing applied to the merge result. The types available are:
|produces a merge result with oXygen Author track change processing instructions.|
|performs three to two-way simplification and shows as many changes as possible.|
|performs three to two-way simplification and shows conflicts for further resolution. Simple, non-conflicting adds, deletes and modifications are automatically resolved.|
|performs 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.|
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:
|produces either a deltaV2 result or a simplified delta result.|
|produces a result format which is an XML file with processing instructions used in the accept/reject interface of the oXygen XML editor/author|
This section lists the number of '.jar' files in the release. They should always be included on the classpath while executing merge.
deltaxml-merge.jarAPI. Please see Catalog Resolver Customizations for further details of the modifications we have made.
flexlm.jar and EccpressoAll.jar
saxon9pe.jar, xercesImpl.jar and icu4j.jar
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.
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.