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:
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.
Option | Description | API | Default Value |
|---|---|---|---|
Word by word | Specifies whether to split text into words to provide a more granular comparison result | word-by-word | True |
CALS Table Processing | Enables CALS table specific processing | cals-table-processing | True |
HTML Table Processing | Enables HTML table specific processing | html-table-processing | True |
Output
Options in this group relate to the output of the comparison.
Option | Description | API | Default Value |
|---|---|---|---|
Output type | Switch between FrameMaker Tracked Changes format and standard DITA format | output-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) | phrase-element-name | ph |
Tracked changes in tables | How to output changes found in the table structure that are not supported by FrameMaker | framemaker-tcs-table-change-mode | Push changes down |
Tracked changes author | The author name associated with each change (applies to Tracked Changes format only) | deltaxml | True |
Special
This group consists of more advanced options for dealing with problems that may occur in comparison results.
Option | Description | API | Default Value |
|---|---|---|---|
CALS table change fixing | How to fix invalid CALS tables | invalid-cals-table-behaviour | Propagate up |
DITA steps resolution | Method for resolving conflicts between steps-unordered elements and mutually exclusive steps | steps-conflict-resolution | Use B container |
Validate inputs | Control whether XML validation is performed on the input documents | validate-inputs | True |
Report warnings in | Specify method for reporting recoverable errors and warnings | warning-report-mode | True |
Modified attribute version | Specifies which version to show if an attribute is modified (attribute changes can not be represented in the output format) | modified-attribute-mode | Authomatic (B) |
Setup
Option | Description | API | Default Value |
|---|---|---|---|
DITA Compare Path | Set the full plath of the jar-file for the locally installed DeltaXML DITA Compare product | [not-applicable] | [none] |
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