Usage

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'.

Caution: 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

Note: 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

Comparison

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

Word by word
Specifies whether to split text into words to provide a more granular comparison result Trueword-by-word
CALS Table Processing
Enables CALS table specific processing Truecals-table-processing
HTML Table Processing
Enables HTML table specific processing Truehtml-table-processing

Output

Options related to the output of the comparison

Output type
Switch between FrameMaker Tracked Changes format and standard DITA formatFrameMaker tracked changesoutput-format
Text wrapper element
The name of the DITA element used to wrap changes found in text content (not applicable for Tracked Changes format)phphrase-element-name
Tracked changes in tables
How to output changes found in the table structure that are not supported by FrameMakerPush changes downframemaker-tcs-table-change-mode
Tracked changes author
The author name associated with each change (applies to Tracked Changes format only)Truedeltaxml

Special

More advanced options for dealing with problems that may occur in comparison results

CALS table change fixing
How to fix invalid CALS tablesPropagate upinvalid-cals-table-behaviour
DITA steps resolution
Method for resolving conflicts between steps-unordered elements and mutually exclusive steps Use B containersteps-conflict-resolution
Validate inputs
Control whether XML validation is performed on the input documentsTruevalidate-inputs
Report warnings in
Specify method for reporting recoverable errors and warnings Truewarning-report-mode
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)modified-attribute-mode

Setup

DITA Compare Path
Set the full plath of the jar-file for the locally installed DeltaXML DITA Compare product[none][not-applicable]

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