Guide to DeltaXML DITA Merge Result Formats and Types

1. Introduction

The Dita Merge 1.1 release has introduced some additional result formats. This guide summarizes their differences and offer advice as to which may be appropriate for different user requirements and use-cases.

deltaV2rule processed deltaV2simplified deltatwo way results
Number of inputs3+3+3+3
Extract all inputs
Supports nested change
Use with editor accept/reject
Supports DITA MARKUP format
Use with DeltaXML oXygen plugin
Suitability for automated processing✔✔✔✔✔✔✔✔✔✔✔
Suitability for manual resolution✔✔✔✔✔

2. Considerations

2.1. Number of inputs

The DitaConcurrentMerge class is designed as n-way merge system and therefore supports an unlimited number of input DITA files. The use of a common ancestor to guide the alignment process in addition to two versions or branches being merged means that a minimum of three DITA inputs are required.

The DeltaXML DITA Merge 1.1 release introduces a new ThreeWayDitaMerge class. This has all of the capabilities of the n-way DitaConcurrentMerge class but provides some additional capabilities suited to the three way use cases such as the ability to represent and simplify the merge results using a two-way representation.

2.2. Extract all inputs

A complete representation of each input file means that there is no loss of information in the merged file, i.e. any one of the input files could be extracted as an XML tree. This is a general property of the merge system.. However some result formats and representations provide simplifications or processing that restrict this capability. In particular:

  • The rule processing system used with deltaV2 and simplified result formats automatically process changes such as adds and deletes. After these changes are processed the full details of these changes cannot be reversed and therefore all of the inputs cannot be extracted.
  • The three-to-way way result simplification process by design removes information associated the the ancestor input in order to emphasise changes between the branches being merged.

2.3. Supports nested change

The merge system supports generating optimal results which avoid repetition of content from the inputs. When three or more inputs are involved such a representation involves nested change. The simplified result format and the three-to-two way result simplification process are designed to remove the need for a nested change representation. This allows the results to be used with simpler user interfaces and editing processes, but with the potential loss of some detail in the result. The support for nested change is closely related to the types of user-interface available with the various result types.

2.4. Use with editor accept/reject

XML editors often provide accept/reject style user interfaces that can be used to process track-change recording and in some cases comparison results. This type of user interface supports add and delete operations and is unsuited to general n-way merge result processing. However the three-to-two way processing options available with the ThreeWayDitaMerge class were designed to support this type of interface with the compromise that in some cases a little information, typically related to the ancestor input, cannot be presented to the user.

2.5. Supports DITA MARKUP format

The DITA Markup output format uses rev and status attributes to identify change. These attributes can be added to many DITA elements. The rev attribute can take any value and the status attribute can take one of the following values: 'changed', 'new', 'deleted', 'unchanged'. The result is represented by add and delete operations by setting rev attribute as 'deltaxml-add' or 'deltaxml-delete'. The three-to-two way processing options availble with ThreeWayDitaMerge are designed to support DITA MARKUP result format format. However, in some cases, information related to ancestor input cannot be presented to the user.

2.6. Use with DeltaXML oXygen plugin

A user-interface specific to n-way merge operations has been developed in order to demonstrate the possibilities that an n-way algorithm and interface can provide. DeltaXML has developed a plugin or 'add-on' for the oXygen editor for content used with the editor's author mode. This allows the user to deal with n-way conflicts as well as non-conflicting changes such as additions and deletions. A web-based resolving system ('XMLFlow') is also under development. Both of these systems are designed to handle nested change.

2.7. Suitability for automated processing

The n-way form of the deltaV2 result format was designed for ease of XSLT processing and conversion into other types of result. Using this result representation, it is easy to make processing decisions at various points in the XML tree as each element has information about any descendant change using the deltaV2 attribute. The format is also minimal so that information is not repeated unnecessarily.

2.8. Suitability for manual resolution

The deltaV2 format has information throughout the XML tree hierarchy which becomes laborious to process manually, for example when a user wishes to resolve merge conflicts or changes using an XML editor. A major driver in the design of the simplified delta format was to make manual processing of merge results easier. The simplified result can also be processed automatically using XSLT or other technologies, however the change representation is not as rich as deltaV2.