Technical Specification

Overview

DeltaXML DocBook Compare compares two well-formed DocBook files (with the same root element) and generates a DocBook result highlighting the differences between the inputs using either DocBook's own revisionflag attributes on elements or the tracked changes markup for the popular XML editors Arbortext, oXygen, and XMetaL.

DocBook's Change Markup

Textual changes are highlighted by wrapping the changed text in <phrase> elements that specify the revisionflag attribute. Where the phrase element is invalid, textual changes are optionally wrapped with delimiters to show where change has occurred e.g. -[[old-text]]-+[[new-text]]-

Where the inputs specify Doctypes, these are preserved in the result document. If the two inputs have different Doctypes, the result uses the one from the second input.

Track Change Markup

From version 3.0 an alternative output marks changes in the tracked changes format for Arbortext, oXygen or XMetaL.

The Arbortext tracked changes output format uses special tracked change elements. Here DocBook elements can contain Arbortext tracked change elements, and vice versa. One consequence of this approach is that the resulting tracked change document does not conform to the DocBook standard. In order to return an Arbortext tracked change document back to the DocBook standard all changes need to be accepted or rejected.

The oXygen and XMetaL tracked changes output formats use processing instructions to highlight the changes between the documents. Deleted content is contained within a processing instruction itself, whereas added content is identified by two processing instructions marking the start and end of the inserted section. One useful property about this way of tracking changes is that removing all the track change processing instructions leaves the second ('B') version of the document.

Notes

  • Track change format elements or processing instructions (including oXygen and XMetaL) are removed before comparison begins.
  • A DocBook Compare comparison will fail if the inputs are not DocBook files or if one input is DocBook 4.x and the other DocBook 5.x

DocBook versions

DocBook 4.5 and 5.0 are currently supported as result DocBook versions. Other versions may compare with usable results but are not guaranteed to be valid against the specification version. DocBook 4.3, 4.4, 4.5 and 5.0 XML catalog support is provided by the tool. Comparing other versions may make some configuration of the catalog system necessary.

Result Validity

A comparison result will be valid if it is generated by comparing two valid DocBook inputs that are both specified using the same, supported DocBook version. Other scenarios may produce valid results but this cannot be guaranteed.