Usage

Product Versions - 'About' Dialog

Selecting 'DeltaXML → About' shows information about the version of the Adaptor and the comparison products that are currently associated with it. For example:

Associating a comparator

Once a DeltaXML comparison product has been associated with the Adaptor its comparison pipelines can be run. For example, our DITA Compare product provides DITA map, topic and map topicset comparison pipelines.

Note

A comparator product can be associated with the adaptor as detailed in the Adding a Comparator section of the Install Guide.

Running a comparison

We will now take you through the process of running an associated DeltaXML comparator from within oXygen, using DITA Compare 7.0 as our example. There are three available comparison pipelines as shown below:

The DITA MapTopicset comparison pipeline can be run by:

1. Selecting DeltaXML → Compare DITA - MapTopicset..., which will bring up a comparison box:

   

   
   
   

2. Specifying the inputs and output. To choose inputs either:

   • press the Browse buttons to select DITA files from the file system, or
   • choose a document that is already open in oXygen.
   

   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 MapTopicset 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. For example, to view the coloured highlighted differences of a comparison click on the 'Styles' menu, which appears whilst in Author mode, and select the 'Colored revision changes' option. For more detail see here.

Configuring a comparator

A typical DeltaXML comparison pipeline 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 the Adaptor. The configuration panel for a given comparison pipeline is accessed by pressing the 'Configure...' button from a Comparison dialogue box.

An example comparison pipeline configuration is:

• XML Compare's output XML delta comparison pipeline has parameters for Preserve Whitespace, Full Context, Word by Word, Enhanced Match 1 and Indent as shown below:
  
  

  

  These parameters are automatically detected from the DXP configuration file that defines the output XML delta comparison pipeline. In general, user-defined DXP comparison pipelines will also have their DXP parameters automatically detected and made available using this mechanism.

Where there are more options for configuration, we have grouped parameters into different tabs. For instance:

• DITA Compare's MapTopicset comparator has the following sets of parameters:

  • Output

    • Formatting
    • DITA Map
  • Advanced
    • Selection 

  

Note

If a comparison pipeline has no parameters then the 'configure' button will be disabled.

Note

For more information on different products configuration parameters, please see the associated products documentation.

Merge conflict resolver

The merge conflict resolver provides a facility for interactively resolving differences between documents recorded in the output of the DITA Merge product. You will need to have run DITA merge from outside the Adaptor, e.g. on the command line first. 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.

Complex conflict resolution requires human intervention and this facility merely provides an example interface to demonstrate what can be achieved.

Note

There are some incompatibilities between the merge conflict resolver and oXygen versions 15.1 and 15.2 prior to build 2014040317. Therefore the merge conflict resolver is disabled for these versions of oXygen.

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 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 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 

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.