The merge conflict resolver provides a facility for interactively resolving the output of the DITA Merge product. The first step is to convert the DITA Merge output into a DITA document that represents the change using custom merge conflict processing instructions, rather than the deltaV2 elements (and attributes). As a result, the DITA document can now be validated using the relevant DITA DTD (or XSD schema) for its DITA specialisation.
The oXygen form controls associated with the merge conflict processing instructions provide a means for interactively selecting those changes that are wanted. Here the current content of the document is that which is not encoded within a merge processing instruction. Therefore, it is possible to resolve the document, as seen in the Author view, by removing the processing instructions.
A deltaV2 file that has been produced by the DITA Merge product can be converted into a processing instruction form by either selecting the 'DeltaXML → Merge Conflict Resolver → Convert DeltaV2 to Merge PIs' menu option or pressing the button from the DeltaXML Toolbar.
Note: the result of this transformation appears in a new editor window.
The non-attribute changes are coloured in according to their merge 'edit types', which is one of add, delete, or modify, where:
In addition to adding coloured background shading, changes are also marked by one of two form controls:
Once the wanted version of a change has been selected it can be resolved in one of three ways:
It is possible for the highlighting of the change to become out of sync with the document, such as when oXygen's undo operation is performed. In these cases, the 'refresh highlighting' action should restore the correct colour highlighting of merged content. This can be achieved by either selecting the 'DeltaXML → Merge Conflict Resolver → Refresh Highlighting' menu option or pressing the button from the DeltaXML Toolbar.
Once a DeltaXML comparison product has been associated with the Adaptor its 'comparators' can be run. For example our DITA Compare product provides DITA map and topic comparators.
Note: A comparator product can be associated with the adaptor as discussed in the Adding a comparator section of the installation instructions
We now take you through the process of running an 'oXygen' enabled DeltaXML comparator, using the DITA Compare 5.0 as our example. The DITA map comparison can be run by:
Selecting DeltaXML → Compare DITA - Map..., which will bring up a comparison box that looks similar to
Specifying the inputs and output (IO). Either:
The comparison result can have coloured differences, when appropriate CSS styling has been associated with the document type. In the case of a configured DITA product the output should look something like the screenshot below (for a map comparison). In this example, note that differences are coloured in the map manager, and also in the editor for a specific topic.
Note: Some extra CSS configuration is required for oXygen in order to colour DITA maps (as documented here).
A typical DeltaXML comparator has some associated parameters for controlling how the comparison is performed and what type of output is produced. Most of these parameters can be configured from within this Adaptor. The configuration panel for a given comparator, is accessed by pressing the 'Configure...' button from a 'Comparison' dialogue box.
Some example comparison configuration windows include:
Core's 'delta XML output' comparator has the following five parameters
These parameters are automatically detected from the DXP configuration file that defines the 'delta XML output' comparator. In general, user defined DXP comparators will also have their DXP parameters automatically detected and made avialable using this mechanism.
Note: An empty configuration box is displayed for DXP pipelines that have no parameters.
DITA Compare's map comparator has the following 'Output Formatting' parameters
The DITA Compare comparators' parameters have been grouped into two levels. In the case of the above example, the first level is 'Output' and the second level is 'Formatting'.
Reviewing and resolving concurrently merged changes presents some new and interesting challenges for user interface design. The Merge Resolver represents a first generation approach to solving this problem, providing a basic level of functionality. Some issues are:
We hope you find this tool to be useful and welcome feedback.