DITA Compare Parameters

'Automatic' parameter values

Where parameters can have the value automatic (generally used as the default value for that parameter), their actual value is calculated when the inputs are compared. This calculation is based on the values of other parameters; in the case of DITA Compare this is typically the 'output-format' parameter. Here, the idea is to set the value used for the parameter to that which is most appropriate for the given output format. When this automatic behaviour is inappropriate, the actual value of each parameter can be manually set to a specific values using the usual mechanisms. See the documentation for the individual parameters for details on what settings will be used.

Parameter Definitions

The parameter names available on the command-line tool and in the APIs are slightly different. In the command-line version, they are written as lower case words separated by a hyphen (e.g. validate-inputs). In the Java API version of the product, they can be accessed using set/get methods that use a camel-cased version of the name (e.g. setValidateInputs and getValidateInputs). In the .NET API version of the product, they are accessed as Properties, again using a camel-cased version of the name (e.g. ValidateInputs). The names used below correspond to the command-line name.

Output Parameters

These parameters enable the form of the output to be configured.

Non-format specific output parameters.

The output parameters that are either used to specify a specific output type or apply to all output types.

Note that map output type specific configuration is contained in the DITA Map output group.

grouping

Specifies whether adjacent changes (insertions or deletions) should be grouped into a single insertion and/or deletion block. One benefit of this is that changes to a consecutive group of words within a sentence are gathered into one insertion and one deletion block, rather than a series of individual word swaps. This makes it easier to read and understand the changes.

Note that when CALS table processing modes are selected, then this grouping mechanism is turned off within the context of these tables. The table processing has its own specialised grouping mechanisms.

The default value is 'false'.

indent-output

Sets whether the result should be indented.

If run with a compare method that produces a serialized result, a value of yes causes the output to be pretty printed.

This parameter can take the following values:

• yes The value representing the String value 'yes'. Output is indented.

• no The value representing the String value 'no'. Output is not indented.

The default value is 'no'.

map-result-structure

Specifies how the result map is constructed.

The available result structures are defined in terms of the result origin , which is the input that is being used to form the basis of the output. See the map-result-origin parameter documentation for more details.

This parameter can take the following values:

• topic-set The result map will contain a flat list of topic references that appear in the order that they were first encountered in the result origin .

• map-pair The result map contains two submaps: the ' updated ' result origin map (and submaps); and the ' missing ' topic references map.

• unified-map The result map contains: the ' updated ' result origin map; and also includes deleted topic references in positions as close as possible their original location.

The default value is 'topic-set'.

map-uncompared-topic-markup

What action to perform on topics that are not compared. Some DITA aware publishing tools do not make use of revision attributes of a topicref on the referent (i.e. the topic that is being referenced). In these cases, it can be useful to mark the top-level topic element, which is being referenced by the topicref, with appropriate revision and/or status attributes. However, for output formats that are not intended for publication, such as the editor specific tracked change formats, marking up the root element on a topic file as added or deleted, could be counter productive.

This parameter can take the following values:

• auto When DITA Markup is selected as the output format, behave as if 'mark-change' had been selected, otherwise behave as if 'leave-alone' had been selected.

• mark-change Mark the top-level topic element of uncompared topics as added or deleted, in the manner specified by the other topic level parameters.

• do-not-modify Do not update the uncompared topics.

The default value is 'auto'.

map-topic-exception-propagation-mode

What action to perform when there is an exception raised during the processing of a topic during a map file comparison.

This parameter can take the following values:

• fast-fail Propagate the exception as quickly as possible to the map comparison.

• phase-fail Propagate the exception at the end of each phase of the comparison. Here, all topics are progressed to the end of the given comparison phase before the exception is thrown.

• slow-fail Propagate the exception once other topics and map-level operations have completed their processing.

The default value is 'slow-fail'.

output-format

Specifies what type of output is produced.

This parameter can take the following values:

• dita-markup Differences are marked up using DITA's rev and status attributes.

• arbortext-tcs Differences are marked up in the Arbortext tracked change format.

• oxygen-tcs Differences are marked up in the oXygen tracked change format.

• xmetal-tcs Differences are marked up in the XMetaL tracked change format.

• framemaker-tcs Differences are marked up in the FrameMaker tracked change format.

The default value is 'dita-markup'.

preservation-mode

Sets the mode to use for preserving original data.

This mode can be used to preserve information for round trip processing.

The 'automatic' setting will have an effective setting of 'roundTrip' when the output format is a tracked change format and 'docAndAttrib' otherwise.

This parameter can take the following values:

• automatic Chooses the most appropriate setting based on the output format. If tracked changes are being produced, this will be 'roundTrip', otherwise 'docAndAttrib' will be used.

• document Preserve document typing information.

• docAndAttrib Preserve document typing and original attribute information.

• roundTrip Preserve document type, entity usage, and attribute usage data.

• entityRef Enhance round-trip processing by analysing entity contents.

• nestedEntityRef Enhance round-trip processing by analysing both entity and nested entity contents.

The default value is 'automatic'.

DITA markup output format specific parameters.

The DITA markup output format specific parameters provide control over how the 'rev' and 'status' attributes are used to represent change.

add-outputclass-atts

Specifies whether to include an outputclass attribute for marking changes.

NOTE: This option only applies to the DITA Markup format.

The default value is 'false'.

add-revision-atts

Specifies whether the result should use 'rev' attributes to mark change. When this property is true, any 'rev' attributes in the input that match the regex pattern in 'remove-rev-attribute-regex' are stripped before comparison.

The default value is 'true'.

add-status-atts

Specifies whether the result should use 'status' attributes to mark change. When this property is true, any 'status' attributes in the input are stripped before comparison.

The default value is 'true'.

include-deleted

Specifies whether to include deleted content in the result.

If set to false , the result will only include unchanged and added content.

The default value is 'true'.

new-outputclass

Specifies the string value to use for the outputclass attribute of added content.

Added elements and text (via the <ph> parent) will have this string set as the value of the outputclass attribute in the result.The default value is 'deltaxml-add'.

new-revision

Specifies the string value to use for the rev attribute of added content.

Added elements and text (via the <ph> parent) will have this string set as the value of the rev attribute in the result.The default value is 'deltaxml-add'.new-version-attsSpecifies attributes to place on to added elements in the result.

The default value is 'deltaxml-add'.

old-outputclass

Specifies the string value to use for the outputclass attribute of deleted content.

Deleted elements and text (via the <ph> parent) will have this string set as the value of the outputclass attribute in the result.

The default value is 'deltaxml-delete'.

old-revision

Specifies the string value to use for the rev attribute of deleted content.

Deleted elements and text (via the <ph> parent) will have this string set as the value of the rev attribute in the result.The default value is 'deltaxml-delete'.old-version-attsSpecifies attributes to place on deleted elements in the result.

The default value is 'deltaxml-delete'.

phrase-container-exclusions

Specifies any specializations where phrases have been removed from the content model.

These should be listed by full specialization name, e.g. topic/title, in a comma-separated list.

If an element contains any of the items in this list as part of its class attribute, text changes within that element will not be marked using phrase elements.

The default value is ''.

phrase-element-name

Specifies the element name to use in place of <ph> in the result.

If the input documents are specialized documents that have renamed the phrase element, use this method to specify the element name that should be used instead.

N.B. It is assumed that the 'rev' attribute is allowed on the specified element.

The default value is 'ph'.

show-non-phrase-changes

Specifies whether to textually mark changes to text where <ph> elements are not allowed.

If text has changed within an element where phrase markup is not allowed, some other means must be used to process the changes. If this parameter is set to true , the changed text is wrapped in textual delimiters e.g. -[[old text ]]- +[[new text ]]+. If the value is set to false, no markup is used and only the new text is output.

The default value is 'true'.

deleted-id-suffix

Customizes the suffix that is added to ids of deleted element whose value is changed because of duplication.

The default value is '_deleted_'.

added-id-suffix

Customizes the suffix that is added to ids of added element whose value is changed because of duplication.

The default value is '_added_'.

Tracked changes configuration parameters.

The tracked changes output format specific parameters provide a way of configuring tracked change output and editor/format specific output.

framemaker-tcs-table-change-mode

Specifies how changes in tables should be tracked.

The FrameMaker editor cannot track the addition or deletion of a row or cell within a table. Such changes can be pushed down to the cell level, pushed up to the table level (e.g. a CALS 'table' element), or ignored. The advantage of pushing the changes down to the cell content level, is that this provides the highest level of change granularity, at the cost of having to accept or reject every changed cell in the table independently.

The push up processing means that any table that contains a row or cell level update is represented by a table level add and delete.

The ignore option is similar to the way in which track changes within tables are handled in FrameMaker; as neither row insertion and deletion or cell splitting and merging is tracked. However, for clarity this mode of operation ignores all changes within a table, it simply produces the 'B' version of the table.

This parameter can take the following values:

• down Changes in rows and cells are pushed down to the cell content level.

• up Changes in rows and cells are pushed up to the table level.

• ignoreAll changes in a table are ignored.

The default value is 'down'.

oxygen-tcs-deleted-space-mode

Specifies how deleted spaces should be handled.

Prior to oXygen 14 whitespace within the deleted content of a processing instruction were sometimes not displayed correctly. A work-around was to normalise the space within a deleted region.

This parameter can take the following values:

automaticChooses the delete space processing mode based on the declared oxygen-tcs-version parameter.normlizeAllows deleted text to be viewed correctly prior to oXygen 14 release.keepKeeps the original whitespace formating of the deleted region.

The default value is 'automatic'.

oxygen-tcs-version

Specifies the version of oXygen editor used to display, accept and reject the tracked changes.

The format of the version is either '[0-9]+' or '[0-9]+.[0-9]+' without the enclosing string quotes, where: the first number sequence is the major number; and the optional second number sequence is the minor number.

This parameter is used to automatically set the relevant backwards compatibility options related to the oXygen tracked changes format. For example, prior to oXygen 14.0 release deleted whitespace needed to be normalised in order to consistently generate a reasonable result.

The default value is '11.2'.

tracked-changes-author

Specifies the author name that is embedded into the generated insertion and deletion processing instruction.

The default value is 'deltaxml'.

tracked-changes-date

Specifies the time-stamp that is embedded into the generated insertion and deletion processing instruction. The default time-stamp is that of the time that the comparison is run.

The default value is 'xsl date'.

xmetal-tcs-table-change-mode

Specifies how changes in tables should be tracked.

The XMetaL editor cannot track the addition or deletion of a row or cell within a table. Such changes can be pushed down to the cell level, pushed up to the table level (e.g. a CALS 'table' element), or ignored. The advantage of pushing the changes down to the cell content level, is that this provides the highest level of change granularity, at the cost of having to accept or reject every changed cell in the table independently.

The push up processing means that any table that contains a row or cell level update is represented by a table level add and delete.

The ignore option is similar to the way in which track changes within tables are handled in XMetaL; as neither row insertion and deletion or cell splitting and merging is tracked. However, for clarity this mode of operation ignores all changes within a table, it simply produces the 'B' version of the table.

This parameter can take the following values:

• down Changes in rows and cells are pushed down to the cell content level.

• up Changes in rows and cells are pushed up to the table level.

• ignoreAll changes in a table are ignored.

The default value is 'down'.

DITA map configuration parameters.

The DITA Map configuration parameters apply to all output formats. They are used to force outcomes, control conflict resolution, control scope, and specify which document's structure is the basis of the result.

map-backup-suffix

When the map comparison needs to backup a file before it can be compared it appends the '.' character followed by this suffix to the existing file name. Note that if the file already exists then an IOException will be thrown.

The default value is 'bak'.

map-clean-temp

Specifies whether to clean temporary files introduced when performing the comparison.

During the comparison those topics that are compared are initially backed up into a file

This parameter can take the following values:

• yes Clean temporary files created during the map comparison.

• no Do not clean temporary files created during the map comparison.

• auto Clean the temporary files only when the comparison is being performed on a copy of the input.

The default value is 'auto'.

map-pair-remaining-map-name

When the map-result-structure parameter is set to map-pair, the comparison result contains two maps. An updated version of the existing origin map, and a map containing those topic references that were in the original comparison, but not in the existing origin map.

Note that when the map-scan-topics-for-references is set to true , then the topics references within a map (and its submaps) also includes those references that are contained within the topics themselves.

The default value is 'dxml-remaining.ditamap'.

map-result-origin

When comparing the topics referenced in two maps, one of the maps is declared to be the result origin . This is the map that is used to generate the structure and/or order of topic references in the output.

Note that the map-copy-scope parameter is used to specify what the in-scope referents are (i.e. which resources that are pointed to by the map are considered to be part of the document that the map is defining).

This parameter can take the following values:

• A The first 'A' document map is being used as the basis of the output.

• B The second 'B' document map is being used as the basis of the output.

The default value is 'B'.

Comparison Parameters

These parameters control how the comparison is performed.

Text comparison configuration parameters.

These parameters control how text is compared and whitespace handled.

whitespace-processing-mode

Specifies how to handle whitespace changes.

When this option is set to 'show' whitespace differences are reported where possible. If the output-format is set to 'dita-markup', this will be wherever the DITA doctype allows text (as opposed to inter-element whitespace). For tracked-changes output formats, all whitespace changes can be shown.

This can lead to a significant amount of marked change throughout the document. When the parameter is set to 'ignore', whitespace differences are not shown; instead the 'B' document's whitespace is kept where possible.

Note that differences in whitespace are never ignored when the XML document explicitly states that the whitespace is important, via the xml:space attribute being set to 'preserve'.

The 'automatic' setting effectively behaves as either 'normalize' or 'ignore' depending on the value of the 'preservation-mode' and the 'output-format' parameters. Here, 'normalize' is chosen when: (1) the lexical preservation mode is set to 'automatic' and the output format is 'dita-markup'; or (2) the lexical preservation mode is set to either 'document' or 'docAndAttrib'. In all other cases, the automatic preservation mode is treated as if it were 'ignore'.

This parameter can take the following values:

• show Display the differences in whitespace where possible.

• cdata Ignore differences in whitespace, unless they occur within a CDATA section (or are explicitly preserved).

• ignore Ignore differences in whitespace that is not explicitly preserved.

• normalize Normalize whitespace in inputs before comparison.

• automatic Chooses the most appropriate mode based on other parameter settings. This is dependent on two other parameters 'output-format' and the 'preservation-mode', as discussed in the main whitespace processing mode documentation.

The default value is 'automatic'.

Note

The ignore parameter value only affects differences in whitespace. That is, the whitespace content exists in both A and B documents, but the whitespace characters in the whitespace content are different.

word-by-word

Specifies whether to perform detailed text comparison or not.

If set to true , text is split into words before comparison. This allows individual word changes to be detected.

The default value is 'true'.

character-by-character

Specifies whether to perform detailed character comparison or not.

If set to true, changes shown down to individual characters.

The default value is 'false'.

For more details on Character by Character comparisons see here.

Table comparison configuration parameters.

These parameters control how tables are compared.

cals-table-processing

Specifies whether to apply CALS table processing.

CALS table processing ensures that when valid (both syntactically and semantically according to the OASIS CALS table model documentation) input tables are provided the result will be a valid CALS table.

Simple changes to the table, such as changing the contents of an entry, adding a row or column are generally represented as fine grain changes. Because CALS entries can overlap or span multiple rows and columns, some types of change are difficult to represent at fine granularity, whilst ensuring validity. In these cases changes are represented at row (ie, groups of added/deleted rows) or even whole-table granularity.

Setting this parameter to false turns off this processing, therefore it is possible to generate an invalid table. However, if table validity is not a concern changes may be represented at finer granularity.

The default value is 'true'.

invalid-table-behaviour

In order to ensure that only valid CALS tables are passed to our specialized CALS table processing, each input table is marked either valid or invalid. This parameter declares what type of processing should be used for those tables that are marked as invalid. The 'warning report mode' parameter configures how recoverable errors are reported.

Three options are provided: fail, propagate up, and compare as XML. The fail option stops the comparison by throwing an appropriate exception (that includes the errors identified by the validity checker). The propagate up option ensures that changes to an invalid table (or more specifically 'tgroup') are represented at the table level. The compare as XML option essentially compares the tables as if they were well-formed XML.

Note that the results of the compare as XML option can differ from comparing the tables without CALS table processing enabled, as a small amount of CALS specific processing is applied to invalid tables in order to allow them to be compared against a similar valid table.

This parameter can take the following values:

• fail Throw an exception.

• propagateUp Propagate the changes to the table-level.

• compareAsXml Compare the table content as well-formed XML.

The default value is 'propagateUp'.

DITA configuration parameters.

The DITA configuration parameters apply to all output formats. They are used to control both conflict resolution and which topics are considered to be part of the document.

remove-rev-attribute-regex

'rev' attributes in the input could be confused with those used to represent change in the output. This parameter specifies the regular expression that matches 'rev' attributes to be stripped.

'rev' attributes that match this regex pattern are only stripped when the 'add-revision-atts' property is true.

The default value is 'deltaxml-.*'.

steps-conflict-resolution

Specifies how to resolve conflicts between a task body's mutually exclusive steps and steps-unordered elements.

A task's body must have precisely one of either the steps or steps-unordered elements. When one input's task body has a steps element and the other a steps-unordered element, the output cannot contain both. Therefore, the comparison is configured to compare the children of the steps and steps-unordered elements, and choose the name of the parent element as follows:

This parameter can take the following values:

• preferA Use the element name from the 'A' document to contain the compared entries.

• preferB Use the element name from the 'B' document to contain the compared entries.

• preferSteps Use a steps element to contain the compared entries.

• preferStepsUnordered Use a steps-unordered element to contain the compared entries.

The default value is 'preferB'.

use-ids-as-keys

Specifies whether to use id attribute value as keys in order to provide identity during comparison.

If set to true , elements with the same name and id value at the same XML tree level will always be matched, regardless of their content.

This setting should only be used if id attribute values are consistent across versions.

The default value is 'false'.

strict-task-model

Specifies whether inputs are using the “strict task model” added in DITA 1.2 (which reflects how tasks are defined pre-1.2) or the “general task model” which allows for a looser definition of elements under <taskbody>. Set false to use the general task model.

The default value is true.

Ignore inline structural changes parameters.

These parameters control which DITA elements are marked as inline structural changes.

ignore-inline-formatting

If set to true, any changes that consist only of the addition, deletion or modification of DITA inline markup elements are not noted as changes.

When comparing the following 2 versions with ignore-inline-formatting switched on, no changes are marked up.

<p>This is an important point</p>

<p>This is an <b>important</b> point</p>

The default value is 'false'.

inline-formatting-elements

Sets the comma and/or space separated list of inline formatting elements. Only active when ignore-inline-formatting is set to true.

This parameter overrides the built in list of DITA inline elements. If the parameter ignore-inline-formatting is set to true then the addition, deletion or modification of these elements will not be treated as changes.

The default value is "apiname, b, cite, cmdname, codeph, filepath, i, lines, msgnum, msgph, parmname, pre, q, sep, sub, sup, systemoutput, term, tm, tt, u, uicontrol, userinput, var, /wintitle".

add-inline-formatting-elements

A comma and/or space separated list of inline formatting elements, which will be added to the value of the inline-formatting-elements parameter.

Use this list to add to the value of inline-formatting-elements which you wish to be ignored when considering change processing.

Elements in this list are added to the set in inline-formatting-elements, before the set in remove-inline-formatting-elements has been removed.

The default value is "".

remove-inline-formatting-elements

A comma and/or space separated list of inline formatting elements, which will be removed from the value of the inline-formatting-elements parameter.

Use this list to remove from the value of inline-formatting-elements when the defaults include elements you do not wish to be ignored when considering change processing.

Elements in this list are removed from the set in inline-formatting-elements, after the set in add-inline-formatting-elements has been added.

The default value is "".

Element moves handling parameters.

These parameters control element moves handling and defines the values for revision attribute.

detect-moves

If set to true, them elements moves are handled if the elements have ids on them.

If this feature is set to true then it overrides the value of the parameter ‘use-ids-as-keys’.

move-source-revision

Specifies the string value to use for the rev attribute for source of moved content.

move-target-revision

Specifies the string value to use for the rev attribute for target of moved content.

remove-move-source

Remove move source. This is by default disabled.

MathML comparison configuration parameters.

mathml-processing

Specifies whether to apply MathML processing.

MathML processing ensures that when valid (both syntactically and semantically according to the OASIS MathML model documentation) input are provided the result will be a valid MathML.

Simple changes to the MathML equation, such as changing the contents of a MathML element, adding an element is generally represented as fine grain changes. Because MathML attributes can't be represented in the author view, some types of change are difficult to represent at fine granularity, whilst ensuring validity.

Setting this parameter to false turns off this processing, therefore it is possible to generate an invalid MathML equation. However, if table validity is not a concern changes may be represented at finer granularity.

The default value is "true".

mathml-granularity

Specifies the granularity at which the differences between the two MathML expressions will be represented from the DocumentComparator.

This parameter can take the following values:

• adjacent Reports the differences to the MathML by repeating A and B MathML inputs adjacent to each other.

• detailedAdjacent Reports the differences to the MathML by repeating the A and B MathML inputs adjacent to each other, with individual changes highlighted.

• inline Reports the differences within the MathML without duplicating A and B.

The default value is "inline".

Image comparison parameters.

image-compare

Specifies whether to compare images. For more details pleasesee. By default image comparison is enabled.

output-image-ref-form

Specifies output image ref form after image comparison. By default outputs the href attribute as it appears in the source document

svg-processing

Sets whether to do should do SVG comparison. SVG comparison is recommended as it will use SVG XML-aware features when comparing two SVG images to ensure that the result can be rendered.

svg-granularity

Specifies the granularity at which the differences between two SVG images will be represented. SVG Granularity can be of two types - 'detailed-adjacent' and 'adjacent'.

The 'adjacent' mode will display both SVG images side-by-side, and 'detailed-adjacent' will do the same while also adding styling to highlight individual changes. The default is detailed-adjacent.

input-a-svg-markup-style

Sets the Input A SVG markup style setting for SVG comparison results. The default is "red" and DITA Compare expects the style in the same format.

input-b-svg-markup-style

Sets the Input A SVG markup style setting for SVG comparison results. The default is "red" and DITA Compare expects the style in the same format.

svg-fallback

Sets whether to fallback to ADJACENT SVG granularity will fallback if SVG exceeds the number changed elements defined by FallbackChangePercentage.

svg-fallback-change-percentage

Sets fallback change percentage setting for SVG comparison results. The default value is 30.00%.

invalid-referenced-svg-behaviour

Sets the mode to use for handling invalid referenced SVG. There are three behaviours - fail, warn, ignore. The default value is fail.

svg-z-index

Set whether SVG Z-Index representation is enabled. Uses move handling within SVG Comparisons to markup Z-index changes.

z-index-svg-markup-style

Sets the Input Z SVG markup style setting for SVG comparison results. The default is “purple” and as SVG color can be provided as color names, RGB or RGBA values, HEX values, HSL or HSLA values.

svg-numeric-tolerance

Sets whether to use SVG numeric tolerance. SVG comparison will check co-ordinate values are within specified tolerance and therefore can be considered having negligible change.

svg-numeric-tolerance-value

Sets the numeric tolerance value for SVG comparison results. The default is 1%, but can given as a fixed value. Adding '%' will switch value to percentage.

Advanced Parameters

The advanced settings parameters provide a finer level of control over the comparison, the output and error reporting.

Note that changing the default values of some of these parameters can affect the validity of the result, in the sense that the output may not conform to the DITA specification.

Parameters used for validation and reporting.

These parameters are used to specify what validation is performed and how the errors and warnings are reported.

validate-inputs

Specifies whether to validate input documents.

If set to true and the inputs include a DOCTYPE, they will be validated against it. If they are not valid, the compare method will throw an InputLoadException.

The default value is 'true'.

warning-report-mode

Sets the mode to use for reporting recoverable errors and warnings.

This parameter can take the following values:

• messageReport the recoverable errors and warnings as XSL messages, which are typically visible when the comparison is run from a command-line terminal.

• pis Add the recoverable errors and warnings as processing instructions.

• comments Add the recoverable errors and warnings as comments.

• markupAdd the recoverable errors and warnings as document content.

The default value is 'pis'.

Parameters used for selecting what to present.

These parameters are used to specify how unrepresentable change can be handled; when to remove information from the inputs; what information is in scope; and contextual information for referenced content (which can affect how it is displayed).

map-context-href

When set to the non-empty string, this parameter provides a reference to a file that stores the map context information.

This parameter is intended for internal use by the DITA map comparator, which uses it to provide information about the map comparison context. Current information includes the map's result origin and result structure.

The default value is ''.

map-copy-scope

Specifies how to copy a DITA map and its content to an output directory, which maintains the relative structure of the source where this is feasible.

Some maps will contain references to resources that are both marked for copying and cannot be made relative to the map's location. In general, the resources that are referenced from a map (referents), can be grouped according to their 'host' locations, such as a specified file system, web service, version control repository, and content management system (CMS). Each of these 'host' locations is represented as a 'top-level' directory of the output directory (and thus forms a 'forest' of 'tree' structures).

Note the output directory will also contain an additional DITA map file that includes a single reference to the copied map file. This is intended to record where the copied map is within the output directory structure, and provide a convenient point for loading the result into an DITA aware editor.

This parameter can take the following values:

• local References with local scope are copied to the output directory.

• local-and-peer References with local and peer scope are copied to the output directory.

• all All map level references (including external scope) are copied to the output directory.

The default value is 'local'.

map-scan-topics-for-references

Specify whether topics should be scanned when identifying a map's referenced resources (referents). It is possible for a DITA topic to directly refer to other resources rather than make use of DITA keying reuse mechanism. When this is the case, just scanning the maps for resources may not be sufficient, to identify all the resources that are referenced. Turning this option off may significantly improve the performance of the comparison, if it is known that all resources of interest are referenced directly by the maps.

Note that this setting also affects the way in which the resources are identified when copying maps to an output directory.

The default value is 'true'.

modified-attribute-mode

Specifies how modified attributes should be included in the output.

Not all output formats allow the markup of attribute changes. When this is the case, a decision needs to be made on which version of the attribute should be present in the result file. This parameter is used to define what behaviour is required.

This parameter can take the following values:

• automatic The behaviour will depend on other parameter settings, primarily the output-format. If the output format is able to show attribute changes, modified attributes will not be processed differently, otherwise 'B' mode will be chosen.

• B Output the 'B' version of modified attributes and any added ('B') attributes. Note that deleted ('A') attributes will not be output.

• BA Output the 'B' version of modified attributes. Output both inserted ('B') and deleted ('A') attributes.

• A Output the 'A' version of modified attributes and any deleted ('A') attributes. Note that added ('B') attributes will not be output.

• AB Output the 'A' version of modified attributes. Output both inserted ('B') and deleted ('A') attributes.

• encode-as-attributes Output the 'B' version of modified attributes and any added ('B') attributes but additionally show the changes encoded as attributes in the attribute-change ('ac') namespace.

The default value is 'automatic'.

unmarked-change-mode

Specifies how to handle data that cannot contain difference markup.

Some differences between two XML documents cannot feasibly be displayed in a valid output document. These typically include changes to the XML declaration, doctype, internal subset and processing instructions. In these situations it is useful to specify what should be done.

Note that the internal subset can contain local element, attribute, and entity declarations, as well as processing instructions, comments, and entity-references.

This parameter can take the following values:

• B Output the 'B' version of modified items; output inserted ('B') items; do not output deleted ('A') items.

• BdA As 'B' except when processing an internal subset declaration, in which case act as 'BA'.

• BA Output the 'B' version of modified items; output both inserted ('B') and deleted ('A') items.

• A Output the 'A' version of modified items; output deleted ('A') items; do not output inserted ('B') items.

• AdB As 'A' except when processing an internal subset declaration, in which case act as 'AB'.

• AB Output the 'A' version of modified items; output both inserted ('B') and deleted ('A') items.

The default value is 'BdA'.

Parameters used to override or force specific behaviours.

These parameters are used to override detected settings or 'safe' behaviour and force particular outcomes, even if this outcome is not valid.

force-specialization

Specifies whether or not to force result specialization when the input types are different.

If this value is set to false and the input documents are different DITA types, the result document will be left in its generalized form with class attributes to indicate what the specializations are.

If this value is set to true and the input documents are different DITA types, the result document will be specialized to the DITA type of the second input. Please note that this may produce a result document that is not valid against its doctype.

The default value is 'false'.

output-encoding-declaration

Sets the character encoding output to use in the XML declaration. For example, 'UTF-8', 'ISO-8859-1', 'windows-1252', and 'ascii'. Precisely which encodings are available is dependent on the specific Java or .NET runtime environment that you use. Note that an invalid output encoding will cause an exception to be raised.

The 'system' special value is introduced; selecting it has the affect of choosing the 'B' document's character encoding.

The default value is 'system'.

topic-public-id

Specifies the publicId to use for a Topic doctype.

A value should only be passed if you wish to override the default values for the publicId (-//OASIS//DTD DITA 1.1 Topic//EN for DITA 1.1 and -//OASIS//DTD DITA 1.2 Topic//EN for DITA 1.2)

Note that this value is only used if the following are true:

The input documents are different DITA specializations, or only one of them is specialized At least one of the input documents specified a doctype The comparison has not been configured to re-specialize the result document even if the inputs were different types

The default value is ''.

topic-system-id

Specifies the systemId to use for a Topic doctype.

A value should only be passed if you wish to override the default values for the publicId (http://docs.oasis-open.org/dita/v1.1/OS/dtd/topic.dtd for DITA 1.1 and http://docs.oasis-open.org/dita/v1.2/os/dtd1.2/technicalContent/dtd/topic.dtd for DITA 1.2)

Note that this value is only used if the following are true:

The input documents are different DITA specializations, or only one of them is specialized At least one of the input documents specified a doctype The comparison has not been configured to re-specialize the result document even if the inputs were different types

The default value is ''.

xml-version-declaration

Sets the version to use in the XML declaration.

The 'system' special value is introduced; selecting it has the affect of choosing 'B' document's xml-version (as provided by the parser).

This parameter can take the following values:

• 1.0 Ensure the xml version is set to '1.0'.

• 1.1 Ensure the xml version is set to '1.1'.

• system Use the 'B' document's xml version (as provided by the parser).

The default value is 'system'.