Usage

Merge conflict resolver

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.

Preparing the files

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

Note: the result of this transformation appears in a new editor window.

Viewing and selecting the changes

The non-attribute changes are coloured in according to their merge 'edit types', which is one of add, delete, or modify, where:

• added elements have a background colour of green,
• deleted elements have a background colour of red, and
• modified elements have a background colour of either purple or orange.*

*Only changes with an edit-type of modify can contain (or be contained by) a change with the same edit-type. When this occurs it is useful to be able to distinguish the nested change by using a different colour. The colour associated with a modified change is determined by its depth, as determined by the number of changes it is contained in. Here, odd depths have a background colour of purple, whereas even depths have a colour of orange.

In addition to adding coloured background shading, changes are also marked by one of two form controls:

1. An XML content change, which is represented by a pre-fixing form control button with 'Δ' as its label.
2. An attribute change, which is represented by a pre-fixing its associated element with a form control button with '@' as its label.

Resolving changes

Once the wanted version of a change has been selected it can be resolved in one of three ways:

1. by selecting the resolve option from the associated form control.
2. by selecting an editor region that includes the form control and resolving this region by either selecting the 'DeltaXML → Merge Conflict Resolver → Resolve selected delta symbols' menu option or pressing the

   

   button from the DeltaXML Toolbar.
3. by either selecting the 'DeltaXML → Merge Conflict Resolver → Resolve document' menu option or pressing the

   

   button from the DeltaXML Toolbar.

Other operations

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

Using an associated comparator

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

Running a comparison

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:

1. Selecting DeltaXML → Compare DITA - Map..., which will bring up a comparison box that looks similar to

   

   
   

2. Specifying the inputs and output (IO). Either:

   • press the Browse buttons to select DITA files from the file system, or
   • choose an existing member of an IO parameter's 'combo box', which contains all the files already open in oXygen windows and those files that have been previously selected this session.
   Note: the default output is to a new oXygen window.

   
   

3. Pressing the 'Compare' button (to start the comparison).

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)

Configuring a comparator

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:

• XML Compare'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'.

Further Information

Caveats and Limitations

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:

• There may be a short delay when performing merge 'selection' and 'resolve' actions in oXygen.
• Additions and deletions of tables are identified by prefixing the table with an appropriately coloured bar, which has the form control associated with it.
• It is possible for the colour highlighting to lose synchronization with a change, as described above.
• Although it is possible to edit changes this was not the primary goal of the merge resolver. Note: care must be taken when editing at the beginning or end of a change, as the cursor may not be positioned at the correct position. A work around is to always start the editing one character from the beginning or end of a changed region.