Posted8 November 2013
byPhil G. Fearon

Merging DITA files in the oXygen Authoring Tool

Posted8 November 2013
byPhil G. Fearon

In my previous blog post Reviewing XML Documents for an N-Way Merge, I developed some ideas for reviewing XML Documents for an N-Way Merge, based on a prototype web app. Now it’s time to looking beyond simply reviewing document revisions to the active process of accepting and merging them.

In this post I’ve again used DeltaXML’s DITA Merge solution to produce a single ‘deltaV2’ document that collates changes from 4 revision authors. A small set of XSLT output filters (included in the DITA Merge samples) was then applied to the output to produce a file ready for opening in the oXygen XML authoring tool. The DITA Merge demo plugin for the oXygen tool was used to provide the interactive merge features.

Before looking at the plugin capabilities I’d like to first take a look at the ‘vanilla’ oXygen editor’s own excellent track-changes capability, to see what this gives us.

oXygen Authoring Tool. This track-changes mode is suitable for sequential review sessions.

oXygen Authoring Tool. This track-changes mode is suitable for sequential review sessions

As shown above, track-changes mode in oXygen provides very useful features with revisions from multiple authors supported. But, by design, track-changes mode does not support the merging of concurrent revisions, also, all contributing authors/reviewers must be using an editing system that supports oXygen’s own track-change format and must also remember to turn this feature on. Let’s now have a look at how oXygen’s track-changes mode is supported at the XML code level, just in case the XML format can record concurrent editing information even though the application doesn’t:

<p xml:lang="en">
    DeltaXML DITA Merge automatically merges edits from two or more
    <?oxy_delete author="ben" timestamp="20130908T101153+0100" content="editors"?>
    <?oxy_insert_start author="ben" timestamp="20130908T101153+0100"?>
    reviewers
    <?oxy_insert_end?>
    into a single document, so you can accept/reject changes from multiple authors all in one document. With
    <?oxy_delete author="anna" timestamp="20130908T094302+0100" content="DeltaXML "?>
    DITA Merge you are no longer restricted to having only one person working on a document.
</p>

<p>
    <?oxy_delete author="chris" timestamp="20130908T103006+0100" content="It is relatively easy to work on a document which is reviewed by one other person because you just need to compare two documents (or record changes) to see the changes. If there are two reviewers, then it suddenly becomes a lot more complicated, because you need to do two comparisons and then view three different documents (changes from each reviewer and your original) to produce a new version. For three or more reviewers, you soon run out of screen space to see what is going on."?>
</p>

<p>
    Now, with
    <?oxy_delete author="anna" timestamp="20130908T094319+0100" content="DeltaXML "?>
    DITA Merge, this job becomes much, much easier, because
    <?oxy_delete author="anna" timestamp="20130908T094308+0100" content="DeltaXML "?>
    DITA Merge merges all the changes into a single document.
</p>

<p>
    <?oxy_delete author="anna" timestamp="20130908T094322+0100" content="DeltaXML "?>
    DITA Merge has a number of different use cases:
</p>

From the above, we can see that the oXygen track-changes mode uses special processing instructions (PI) to indicate a text string that was added deleted or replaced, literal text within the PI is used to indicate the text string affected. Each processing instruction has a DateTime stamp (the timestamp attribute); theoretically, this could be used as a reference to associate changes with each other, but oXygen doesn’t yet (in version 14.2) support this, instead each change is regarded as a separate action. So, to accept a change to a word, you need to actually accept both the deletion of the new word and the addition of the new word – this is actually simpler than it sounds because, in the Review pane, all changes are shown chronologically sorted.

So what does this mean with regard to representing a concurrent-document merge in oXygen? We could, hypothetically, store the necessary information about concurrent changes in oXygen’s own track-changes format by exploiting the timestamp attribute. However, this doesn’t actually get us far because the authoring view won’t associate coincident changes and therefore can’t help a reviewer assess what changes conflict. (Of course using oXygen’s own built-in track-changes conflict can’t occur anyway because all changes are applied to the same document).

We’ve established now the reason why we can’t exploit oXygen’s native track-change features for a document merge, but oXygen’s plugin architecture allows for a custom solution.

The demo-plugin enhanced oXygen Authoring Tool with collated DITA document loaded.

The demo-plugin enhanced oXygen Authoring Tool with collated DITA document loaded

The oXygen document authoring view above illustrates the loaded DITA Merge result rendered with DeltaXML’s demo-plugin. Here, buttons are positioned immediately prior to each document change. The text associated with each change has a background color indicating the type of change, red for a deletion, green for an addition and blue for a text-change. This view indicates how the document would appear if the changes currently seleted in the plug-in were to be applied, contrasting with the approach used by the review-only web prototype where all available change-options are shown in the same view:

The review-only web prototype showing the same collated document.

The review-only web prototype showing the same collated document

Back in the oXygen document view, a dropdown list, revealed when a change-button is pressed, shows the other available options for each change; the currently selected change option is highlighted with a check-mark. Also, the owner(s) of each change are shown to the left of the change text. One potential issue is that the revisions associated with each selected change are not immediately apparent, this is shown however, as soon as you hover the mouse over a change-button.

The dropdown lists show all change options and a ‘Resolve’ action.

The dropdown lists show all change options and a ‘Resolve’ action

Pressing the ‘Resolve’ action-item appended to the list results in the currently selected change-option being absorbed into the document, this results in the change-button disappearing also. All the selected change-options can be resolved at once by pressing the ‘Resolve document’ item on the plugin menu.

Representing changes in the XML code

The demo-plugin exploits its own format for processing-instructions embedded in the XML text content to store change information about specific parts of the XML. This format describes how multiple change to the same text or node were made, using a ‘selected’ parameter to store the currently selected change. Selecting a new change (in author mode) from the change-options dropdown list results in this ‘selected’ parameter being updated. Also, selecting the ‘Resolve’ action for the selected change results in the change being absorbed into the XML and the associated processing instruction being removed. Thus, once all changes have been resolved, there will be no further change-associated processing instructions and we’re left with a normal DITA document.

Summary

Here, I’ve outlined how we can enhance oXygen to support concurrent authoring by using the DITA Merge product alongside a special plugin, and also that this plugin can improve effectiveness even with simple non-conflicting changes by combining an associated ‘add’ and ‘delete’ into a single ‘change’.