DITA Merge Result Formats and Types
Introduction
As a user of DITA Merge you will need to understand the different types of results and when to use them. This page summarizes the result types and their differences and offers advice as to which may be appropriate for different user requirements and use-cases.
Result Formats and Result types
The following table summarizes the result format differences and offers advice as to which may be appropriate for different user requirements and use-cases.
deltaV2 | rule processed deltaV2 | simplified delta | two way results | |
|---|---|---|---|---|
Number of inputs | 3+ | 3+ | 3+ | 3 |
Extract all inputs | ✔ | ✔ | ||
Supports nested change | ✔ | ✔ | ||
Use with editor accept/reject | ✔ | |||
Use with DeltaXML Oxygen plugin | ✔ | ✔ | ||
Suitability for automated processing | ✔✔✔ | ✔✔✔ | ✔✔ | ✔✔✔ |
Suitability for manual resolution | ✔ | ✔ | ✔✔✔ | ✔✔ |
Considerations
Number of inputs
ConcurrentMerge is designed as n-way merge system and therefore supports an unlimited number of input DITA files or trees. 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.
ThreeWayMerge has all of the capabilities of the n-way ConcurrentMerge 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.
SequentialMerge is also designed as a n-way merge system and therefore supports an unlimited number of input DITA files or trees. SequentialMerge requires a minimum of three inputs where each version is derived from the previous version.
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.
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.
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 ThreeWayMerge 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.
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 an 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. This system is also designed to handle nested change.
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.
Suitability for manual resolution
The deltaV2 format has information throughout the XML tree hierarchy that 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 technologies, however the change representation is not as rich as deltaV2.
Result Types
There are various result types available. They are available through an enumeration used by each merger object.
DeltaV2
Our standard delta, using deltaxml attributes and elements to mark changes.
More Info:
Overlapping Hierarchies in DeltaV2
Simplified Delta
Created to make manual resolution of changes easier, although small changes nested within larger changes can be harder to see and there is some change information loss.
The SIMPLIFIED_DELTAV2 option is available in all merge objects, and a rule-processed variant SIMPLIFIED_RULE_PROCESSED_DELTAV2 is available through ConcurrentMerge and ThreeWayMerge.
More Info:
The Simplified DITA Merge Format
Analyzed Delta
Additional delta attributes are used to identify the types of changes. This option (ANALYZED_DELTAV2) is available through all merge objects.
More Info:
Two Way Delta
This is only available for ThreeWayMerge
This form of result presents a three-way merge as a two-way result that may be more familiar to users of systems such as accept/reject.
There are two options: TWO_WAY_RESULT and the rule-processed variant RULE_PROCESSED_TWO_WAY_RESULT.
You can customise the changes shown by using setting the ResultType to RULE_PROCESSED_TWO_WAY_RESULT and configuring RuleConfiguration yourself or you can instead use a separate enumeration, ThreeToTwoResultPreset, which pre-sets the necessary options. The preset allows you to choose between ALL_CHANGES, THEIR_CHANGES, or CONFLICTING_CHANGES. Note: "their" changes refers to the third input added to the merge (the first being the common ancestor, the second considered "your" changes).
Three Way Oxygen Track Changes
This is only available for ThreeWayMerge when using a standard three-way merge.
This option, THREE_WAY_OXYGEN_TRACK_CHANGES, is used to generate a result using the Oxygen XML Editor's track changes processing instructions.
TwoWayResult Format
This is only available for ThreeWayMerge when ThreeWayMergeResultType is set to TWO_WAY_RESULT or RULE_PROCESSED_TWO_WAY_RESULT
When using a three-to-two merge, the TwoWayResultFormat enumeration can be used to control the output used to mark up changes in a result. This is applicable only for two results described in Three To Two Merge Guideand Three To Two Merge Use Cases.
XML_DELTA
Produce a standard deltaV2 result.
OXYGEN_TRACK_CHANGES
A result format that marks changes using the Oxygen XML Editor's track changes processing instructions.
DITA_MARKUP
This uses DITA specific 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, or unchanged.