User Guide
Introduction
DITA Merge provides a powerful solution to identify and process the differences between three or more DITA documents. Its primary use is as a toolkit for integration into other systems or applications via a comprehensive Java API, but it may also be run standalone from a command-line interface or from a REST API.
This user guide introduces you to the DITA Merge product, providing a high-level product description along with a look at the main features and concepts associated with this product. You can find more detailed information on the subjects covered here by following the links to an extensive set of tutorials, samples and papers that complement this product.
The Getting Started page provides quick start guides, including information on dependencies. The Samples and Guides page gives a summary of the code samples we have provided, as well as guides to various aspects of the product. Comprehensive technical implementation information can be found in the Java documentation. See also the REST documentation.
What is DITA Merge?
DITA Merge takes three or more DITA files and merges the changes that have been made, into a single DITA file. It aligns content, identifies potential conflicts, and shows differences in the output.
There are two broad scenarios and also a three-way variant:
Concurrent Merge is useful when there is one ancestor document that has been amended by a number of editors concurrently.
Three Way (Concurrent) Merge allows integration with tools allowing accept/reject processing.
Sequential Merge is useful in a scenario in which each of the versions is a derivative of the previous version.
See this guide to learn more on which type of merge to use.
A common use case for DITA 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 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 within the merge process. Again, different types of output can be produced depending on the intended use of the result.
What can DITA Merge do?
Find all the differences between any set of three or more DITA files (sharing a common root element).
Handle large files without performance degradation.
Display change information in Oxygen or DITA form (available with ThreeWayMerge when using a Three-to-Two merge)
Text processing for differences on a word-by-word basis.
Special processing for formatting elements.
DITA/CALS table structure awareness.
Ignoring changes to non-significant whitespace.
See this page for more information about DITA Merge's features.