Before You Start

Before the plugin can be used for the first time, it must first be installed and configured. The steps required for this are described in the plugin Install Guide

Running a Comparison

A comparison is managed from the Compare DITA Topics form, opened from the DeltaXML > Compare DITA Topics menu item.

Adobe FrameMaker's menu-bar, with the plugin's DeltaXML menu open.

The file-selection method for a comparison is the same as that for FrameMaker's built-in comparison feature. The currently selected file in FrameMaker is taken as the Newer Document, the Older Document is selected either from the drop-down list (showing other files already open in FrameMaker) or by pressing the Browse button.

Once the Older Document has been selected the comparison is started by pressing the Compare button. The comparison result will be opened in FrameMaker and shown as the current document.

The 'Compare DITA Topics' dialog.

Reviewing a Comparison Result

FrameMaker Track Changes

When using this output type, the result of a comparison is opened as temporary file (untitled.xml) in a new editor tab in FrameMaker. Changes are highlighted in red/green foreground colours in the usual way, you can also use the standard Track Text Edits toolbar to move the cursor through each change and accept/reject each change in the usual way.

DITA Markup

When the DITA Markup output type is selected, the result file is opened in FrameMaker but differences are not highlighted in the editor, to highlight the changes, this file needs to be saved and then transformed using FrameMaker's built-in DITA open toolkit to a final output format, such as PDF.

To style document changes within the DITA open toolkit (DITA-OT) output, you will need to apply a special ditaval file, this can be set in the corresponding field in FrameMaker's 'Generate DITA OT Output' dialog. DeltaXML's DITA Compare download includes a suitable ditaval file called 'deltaxml.ditaval'.


Before using the DITA-OT on the comparison result open in FrameMaker, it must first be saved in the usual way with an appropriate filename.

The ditaval file can be specified in the corresponding field in FrameMaker's 'Generate DITA OT Output' dialog.

Once the DITA OT output is generated using the specified ditaval file, the changes will be highlighted - as shown in the PDF rendering below:

The PDF rendering of a comparison generated by the DITA Open Toolkit.

Configuring a Comparison

The default comparison options for the FrameMaker plugin are designed to suit most types of comparison need, these can however be modfied from the 'Comparison Options' dialog, this is opened from the DeltaXML > Options menu item, or by pressing the 'Options' button in the Compare DITA Options dialog.

The Comparison page of the 'Comparison Options' dialog.

The comparison options available are summarised in this section. Each option corresponds to a parameter in the DITA Compare API, e.g. word-by-word. More details on each of the API parameters can be found in the Parameters Appendix of the DITA Compare Reference document.


Some options refer to either the 'A' or 'B' document; in the context of the plugin, these are the 'older' and 'newer' documents respectively.

Comparison Options


Options in this group relate to processing of the XML either before the comparison or immediately afterward.




Default Value

Word by word

Specifies whether to split text into words to provide a more granular comparison result



CALS Table Processing

Enables CALS table specific processing



HTML Table Processing

Enables HTML table specific processing




Options in this group relate to the output of the comparison.




Default Value

Output type

Switch between FrameMaker Tracked Changes format and standard DITA format


FrameMaker tracked changes

Text wrapper element

The name of the DITA element used to wrap changes found in text content (not applicable for Tracked Changes format)



Tracked changes in tables

How to output changes found in the table structure that are not supported by FrameMaker


Push changes down

Tracked changes author

The author name associated with each change (applies to Tracked Changes format only)




This group consists of more advanced options for dealing with problems that may occur in comparison results.




Default Value

CALS table change fixing

How to fix invalid CALS tables


Propagate up

DITA steps resolution

Method for resolving conflicts between steps-unordered elements and mutually exclusive steps


Use B container

Validate inputs

Control whether XML validation is performed on the input documents



Report warnings in

Specify method for reporting recoverable errors and warnings



Modified attribute version

Specifies which version to show if an attribute is modified (attribute changes can not be represented in the output format)


Authomatic (B)





Default Value

DITA Compare Path

Set the full plath of the jar-file for the locally installed DeltaXML DITA Compare product



Log Files and Cached Comparison Results

When performing a number of comparisons in a single session from Adobe FrameMaker, it may be useful to refer back to previous comparisons and revisit the result or check the settings used for a comparison.

Each time a comparison is performed, the result is cached and details sent to a log file, log files are refreshed for each FrameMaker session. Cached results are saved with filenames suffixed with a data-time stamp and stored within the results sub-folder of the DeltaXML user folder. Two log files are also kept in the DeltaXML user folder: plugin-log.txt is for successful comparison operations, plugin-errorlog.txt is for comparison operations that return an error.

The DeltaXML user folder is the user-specific application folder for FrameMaker, with a path of the form: C:\Users\[username]\AppData\Roaming\Adobe\FrameMaker\13\DeltaXML