Overview
DeltaXML DITA Compare compares two well-formed Darwin Information Typing Architecture (DITA) inputs and generates a DITA result file that highlights the differences between the inputs using either DITA's own change markup attributes ('rev' and 'status') on elements or the tracked changes markup for the popular XML editors Arbortext, oXygen, and XMetaL.
DITAs Change Markup
Textual changes are highlighted by wrapping the changed text in phrase elements (<ph> by default) that specify the rev and/or status attributes. Where the <ph> element is not valid, textual changes are optionally wrapped with delimiters to show where change has occurred e.g. -[[old-text]]-+[[new-text]]+
The status attribute may have these values: unchanged, changed, new, deleted. The status attribute will be added with appropriate value where it is allowed. An option lets you control whether or not the status attribute is added. The status attribute is allowed on many different elements in the hierarchy: for example a changed section would have status='changed' and within it each paragraph would have a status attribute with an appropriate value.
The rev attribute may have user-specified values, and you can change the default values that are built into the software. The default values are: deltaxml-add, deltaxml-delete. These will be added with appropriate values, where they are allowed, to show added or deleted text, paragraphs etc. An option lets you control whether or not the rev attribute is added. The ditaval file can be configured to provide different text decoration in your output pipeline, controlled by the value of this attribute.
Track Change Markup
From version 4.0 an alternative output marks changes in the tracked changes format for oXygen or XMetaL. Version 4.1 added the Arbortext tracked changes format.
The Arbortext tracked changes output format uses special tracked change elements. Here DITA 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 DITA standard. In order to return an Arbortext tracked change document back to the DITA 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 DITA Compare comparison will fail if the inputs are not DITA files.
DITA versions
DeltaXML DITA Compare currently supports OASIS DITA 1.1 Other versions may compare with usable results but result validity cannot be guaranteed. DITA 1.1 XML catalog support is provided by the tool, for other versions or specializations some configuration of the catalog system will be necessary.
Comparing DITA specializations
Input documents that are instances of a DITA specialization will be generalized before comparison using the generalization mechanism in the DITA OpenSource Toolkit (DOST). Once comparison has taken place, the result file will undergo specialization, again using the mechanism provided by DOST.
If the two inputs were instances of different specializations, the result file will be specialized using the typing of the second input file where possible. Comparing input files that are instances of different specializations is not recommended.
Result validity
If the inputs are valid instances of v1.1 topic or one of the standard specializations built into DITA v1.1, and the phrase element parameter is left as the default value of <ph>, the result file will be a valid DITA v1.1 document.
Inputs that are instances of a specialization will produce a result that is an instance of the same specialization but due to the way in which generalization/specialization is preformed during the comparison will potentially produce an invalid result, particularly if the scope of the <ph> element or the rev and status attributes is restricted by the specialization.
Tool Dependancy Notes
Controlling PDF output using ditaval markup (when using the DITA Open Toolkit)
DITA-OT version 1.5.3 (or higher) is required for getting ditaval markup to be used when generating XSL-FO for PDF output. The samples directory in the download contains a deltaxml.ditaval file that can be used to highlight addition and deletion markup (by default in green and red respectively).