Breadcrumbs

DocBook Output and Displaying Changes

Output Formats

The DocBook Comparison product can represent the differences between two inputs using a variety of output formats. Each output format has its own limitations on what types of change are supported and where changes are allowed to take place. For example, DocBook's own change markup language does not support changes in attributes.

The DocBook Comparison product currently provides the following output formats:

  1. DocBook Markup. This output format marks differences using DocBook's own change markup scheme.

  2. Arbortext Tracked Changes. This output format marks differences using the Arbortext Change Tracking Markup Specification. See the PTC Arbortext website.

  3. FrameMaker Tracked Changes. This output format marks differences using the FrameMaker Tracked Changes format, which is supported by the Adobe FrameMaker Editor.

  4. oXygen Tracked Changes. This output format marks differences using the oXygen Tracked Changes format, which is supported by the oXygen Editor and Author products.

  5. XMetaL Tracked Changes. This output format marks differences using the XMetaL Tracked Changes format, which is supported by the XMetaL Editor.

The 'default' output format is 'DocBook Markup', which identifies change using DocBook's own change markup scheme as discussed in the section called “DocBook Markup” below.

The remaining output formats represent the differences between two inputs using tracked change formats. Here, the intention is to enable the differences to be viewed, accepted, and rejected in an editor or word-processor that supports the given tracked changes format.

The remainder of this section discusses the output formats in more detail.

DocBook Markup

When using DocBook Markup the output of a comparison is itself a DocBook document. The DocBook Markup output format uses the revisionflag attribute to identify change. This attribute can be added to any DocBook element, taking one of the following values: changed, added, deleted, off. These values can be used to highlight changes between two given versions of a document.
The revisionflag values are used on elements as follows:

  • when an element existed in the original document but is no longer present, a revisionflag="deleted" attribute is added to that element,

  • when an element exists in the new version of the document but was not present in the original a revisionflag="added" attribute is added to that element,

  • for certain elements, attribute changes cause a revisionflag="changed" attribute to be added to the element

In DocBook 4.x, revisionflag attributes are not allowed on certain elements. Changes to these elements therefore cannot be displayed.

Changes to text content are handled slightly differently. Since it is not possible to add attributes to text, it must first be wrapped in an element that can have the attribute added. The <phrase> element is intended for this kind of purpose.

Text that was in the original document but is no longer present is wrapped with <phrase revisionflag="deleted">...</phrase>, text that is only included in the new version of the document is wrapped with <phrase revisionflag="added">...</phrase>.

If text changes are made in a context where <phrase> is not a valid element, there is the option to use textual markers to display the change. This option is controlled using the show-non-phrase-changes parameter, which is set to true by default. Text changes are marked up as follows:

  • text that existed in the original document but is no longer present is wrapped like this: -[[...]]-

  • text that exists in the new version of the document but was not present in the original is wrapped like this: +[[...]]+

  • As well as marking the text in this fashion, the element that contains the text will also have a revisionflag="changed" attribute added to it

If the show-non-phrase-changes parameter is set to false, then only the text from the new version of the document will be output, without any marking.

Arbortext Tracked Changes

When using Arbortext Tracked Changes Markup the output of the comparison is an Arbortext tracked change version of a DocBook document. 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 specification. In order to return an Arbortext tracked change document back to the DocBook specification all changes need to be accepted or rejected (and the tracked change author information has to be removed).

Assuming that the inputs to the comparison are valid DocBook documents and all the changes to the output are accepted (or rejected) as previously discussed, then the resulting document will be a valid DocBook document. Note that in general it is not possible to guarantee that an arbitrary combination of 'accepted' and 'rejected' changes will result in a valid document, due to the granularity of change.

The generated tracked changes use three of the available tracked change elements:

  • atict:add. For inserted content;

  • atict:del. For deleted content;

  • atict:chgm. For attribute modification (outside the context of a table).

Changes within comments and CDATA Sections results in the whole of the old version of the text being marked as deleted, and the whole of the new version of the text being marked as inserted.

The Arbortext tracked change format does not support changes to processing instructions or those comments that are outside the body of the DocBook document. It does, however, support both cell and row level changes within tables.

FrameMaker Tracked Changes

The FrameMaker Tracked Changes Markup output format is a valid Docbook document that includes annotations to represent changes in the document.

This format employs FrameMaker's method for tracking changes, exploiting XML processing-instructions and comments to mark additions and deletions within documents.

The FrameMaker tracked change format is restricted to the Author and WYSIWYG views, these views do not support edits within XML marked as CDATA, changes to CDATA sections are therefore converted to normally parsed XML content. This format uses a pseudo-entity '&fm-double-hyphen;' to allow two adjacent hyphen characters to be represented within comments - which the track change format uses to contain deleted content.

As with most editors, FrameMaker has a few limitations on what types of change can be tracked for different element types, an example is the addition/deletion of table rows. For this specific example, the output format defaults to showing changes as changes in the text content of the row cells. This is affected by the parameter setting for framemaker-tcs-table-change-mode. However, other limitations have not been fully explored and its possible that some changes marked in the output format will be ignored by FrameMaker.

oXygen Tracked Changes

When using oXygen Tracked Changes Markup the output of the comparison is itself a DocBook document. This output format uses processing instructions to identify change, where deleted content is typically contained within the processing instruction and inserted content is typically sandwiched between two processing instructions, one marking the start of the insertion and the other the end. Hence, removing (or ignoring) the processing instructions has the affect of accepting all changes to the document.

Comments and CDATA Sections are handled specially, as processing instructions cannot be placed inside their content. Instead, changes are identified by a sequence of processing instructions that immediately follow the Comment or CDATA Section, which mark the location of the change by using a character counting technique. Here, deleted content is contained in the processing instructions, whereas inserted content is already in the Comment or CDATA Section text itself. This preserves the principle of being able to accept all the changes within a document by either ignoring or removing the tracked change processing instructions.

Similarly with attributes changes are identified by a sequence of processing instructions that immediately precede the element containing the changed attribute.

The oXygen tracked change format does not support changes to processing instructions, or those comments that are outside the body of the DocBook document. It does, however, support both cell and row level changes within tables.

XMetaL Tracked Changes

When using XMetaL Tracked Changes Markup the output of the comparison is itself a DocBook document. This output format uses processing instructions to identify change in a similar manner to that of oXygen tracked change format. However, it does not support changes to attributes, comments, changes within CDATA sections, or row or cell level table changes.

Changes within CDATA Sections are handled by moving the change to the CDATA Section level as a whole. Therefore any textual change with in a CDATA section results in the old version of the whole CDATA section being marked as deleted, and the whole of the new version of the CDATA Section being marked as inserted.

There is a special XMetaL specific parameter (xmetal-tcs-table-change-mode) which controls what happens when row or cell level table changes are present. These changes can be pushed down to the cell content level, where the content of each cell within the changed region is appropriately deleted and inserted; this is the 'default' behaviour. The second option is that changes to rows or cells can be pushed up to the table level, so that the old and new versions of the table as a whole are tracked. The third option is that changes can simply be ignored (which mirrors what the XMetaL editor would do). However, selecting the ignore mode means that all changes within a table are ignored, not just those that are at the 'row' or 'cell' level. This is deliberate, as we believe that partial tracking of changes within a table would be confusing.

Displaying Changes

A DocBook Compare result file contains the information needed to determine the changes between two revisions of a document but in itself it is not able to display those changes in a meaningful way. The next task is to utilise this information in the publishing step for the document so that the changes can be highlighted in formats such as HTML, PDF or even a WYSIWYG editor.

Please note that auto-numbered items such as sections or list items in a document displaying changes may not use the same numbering as in the latest version of the document. This is because deleted items are still given a number. For example, a list that originally had three numbered items but had the middle one deleted will still contain three items in the result but with the middle marked with revisionflag="deleted". When this is converted into a published document, the middle deleted item will be item 2 with the final item being item 3 (rather than 2 as it would be in the latest version of the document).

See the Parameter Definitions in the appendix of the User Guide for details of MathML comparison configuration options.

DocBook Stylesheets (docbook-xsl)

DocBook XSL is a set of stylesheets commonly used for converting DocBook into many different formats such as HTML (single page or chunked), XSL-FO (for processing into PDF), and help page formats. It is highly configurable using stylesheet parameters and it is also customisable, allowing users to redefine how particular DocBook features are processed.

HTML Changebars

DocBook XSL comes with the capability to produce an HTML file that uses text coloring and styling to highlight changes. The stylesheet changebars.xsl in the html directory will produce this output for you. The name is slightly misleading as it doesn't actually produce changebars but does color and style the changed text (red background with strikethrough for revisionflag="deleted", yellow background with underline for revisionflag="added" and green background for revisionflag="changed"). These values are not parameterizable but can easily be customised by redefining the system.head.content template. See the next section on DeltaXML Customisation for more details on customising DocBook XSL.

Customisation

Although DocBook comes with the capability to show changes in published HTML, there is not a similar capability for its XSL-FO output (which can subsequently be converted to PDF). DeltaXML have produced a DocBook XSL customization layer that will add changebars and/or text formatting to the XSL-FO output in order to highlight changes marked using revisionflags. The customisation allows the following settings to be configured:

  • Use of text styling to highlight changes

  • Color, background, decoration and font style of deleted text

  • Color, background, decoration and font style of added text

  • Use of changebars where changes occur

  • Color and style of changebars

The customisation is available on request. You will also require a copy of DocBook XSL (which can be downloaded from http://sourceforge.net/projects/docbook/files/  and an FO to PDF converter (we would recommend RenderX XEP or Apache FOP).

oXygen Editor

When editing DocBook files using a WYSIWYG editor, it is sometimes possible to use revisionflag attributes to highlight changes. This section uses the oXygen editor as an example. oXygen can display DocBook in a text view that shows the raw XML or in Author view which uses CSS to display the document in a fashion more like a word processor would display. It is possible to customize the CSS used to display the document in order to use revisionflag values to highlight change.

Since oXygen 14.0. Choose the 'Colored Revison Changes' option from the 'CSS' toolbar.

Prior to oXygen 14.0. To achieve this customisation, first create a file called deltaxml.css in the frameworks/docbook/css directory in your oXygen installation directory. An example listing that highlights added items as green, deleted items as red and modified items as yellow is shown below:

deltaxml.css
CSS
@import "docbook.css";

[revisionflag=added] {
  background-color: #90ee90;
}

[revisionflag=deleted] {
  background-color: #ff5555;
}

[revisionflag=changed] {
  background-color: #ffff90;
}

Once the file has been created, open the oXygen preferences pane. Select 'Document Type Association' from the list on the left hand side and find the DocBook types in the list that appears (there will probably be separate entries for DocBook 4 and DocBook 5, in which case the following instructions need to be repeated for each).

  1. Change the 'User role' to Developer using the drop-down list at the top.

  2. Select the DocBook entry in the list and press the 'Edit' button

  3. Select the CSS tab and press the + symbol under the list

  4. Enter the URI for the stylesheet (e.g. ${frameworks}/docbook/css/deltaxml.css) and a title for it (e.g. DeltaXML)

  5. If you want to keep the standard CSS as the default, select the Alternate checkbox to make this CSS selectable rather than default

  6. Press OK (3 times to close all preference windows).

In Author view for DocBook files you should now be able to select 'DeltaXML' from the CSS drop-down at the top of the window and see changes highlighted as specified.