DITA Compare Configuration Reference

DITA Compare Configuration Reference

Configurations control the comparison behaviour and are passed at the time a comparison is invoked, either via the API, CLI, or REST configuration file. See JAVA API for equivalent Java methods. For CLI and REST, these are used via configuration file. The configuration file is validated against the XML Schema included in the product distribution in the relevant samples directory e.g. samples/compare/dita/. Associate it with the XSD to enable XML editor autocompletion.

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 outputFormat 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 behavior is inappropriate, the actual value of each parameter can be manually set to a specific value 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 through the configuration file and in the APIs are slightly different. In the Java API version of the product, they can be accessed using set/get methods that use a camelCase version of the name (e.g. setValidateInputs and getValidateInputs). In the configuration file used in the command line and REST API version of the product, they are accessed using a camelCase version of the name (e.g. validateInputs). A .xsd is provided in the distribution to help with configuration file writing. The names used below correspond to the configuration file names.

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.

indentOutput

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.

mapResultStructure

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 mapResultOrigin 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 topicSet.

mapUncomparedTopicMarkup

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 markChange had been selected, otherwise behave as if leaveAlone had been selected.

• mark-change Mark the topLevel 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.

mapTopicExceptionPropagationMode

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 mapLevel operations have completed their processing.

The default value is slowFail.

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

preservationMode

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.

• doc-and-attrib Preserve document typing and original attribute information.

• round-trip Preserve document type, entity usage, and attribute usage data.

• entity-ref Enhance roundTrip processing by analysing entity contents.

• nested-entity-ref 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.

addOutputclassAtts

Specifies whether to include an outputclass attribute for marking changes.

The default value is false.

addRevisionAtts

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 removeRevAttributeRegex are stripped before comparison.

The default value is true.

addStatusAtts

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.

includeDeleted

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.

newOutputclass

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

newRevision

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

new-version-atts

Specifies attributes to place on to added elements in the result.

The default value is deltaxmlAdd.

oldOutputclass

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

oldRevision

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

old-version-atts

Specifies attributes to place on deleted elements in the result.

The default value is deltaxmlDelete.

phraseContainerExclusions

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 '' (empty).

phraseElementName

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.

showNonPhraseChanges

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.

deletedIdSuffix

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

The default value is _deleted_.

addedIdSuffix

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.

framemakerTcsTableChangeMode

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.

• ignore All changes in a table are ignored.

The default value is down.

oxygenTcsDeletedSpaceMode

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 workaround was to normalise the space within a deleted region.

This parameter can take the following values:

• automatic Chooses the delete space processing mode based on the declared oxygenTcsVersion parameter.

• normalize Allows deleted text to be viewed correctly prior to oXygen 14 release.

• keep Keeps the original whitespace formatting of the deleted region.

The default value is automatic.

oxygenTcsVersion

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.

trackedChangesAuthor

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

The default value is deltaxml.

trackedChangesDate

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.

xmetalTcsTableChangeMode

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.

• ignore All 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.

mapBackupSuffix

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

The default value is bak.

mapCleanTemp

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.

mapPairRemainingMapName

When the mapResultStructure parameter is set to mapPair, 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 mapScanTopicsForReferences 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 dxmlRemaining.ditamap.

mapResultOrigin

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 mapCopyScope parameter is used to specify what the inScope 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 is handled.

whitespaceProcessingMode

Specifies how to handle whitespace changes.

When this option is set to show, whitespace differences are reported where possible. If the outputFormat is set to ditaMarkup, this will be wherever the DITA doctype allows text (as opposed to interElement whitespace). For trackedChanges 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 preservationMode and the outputFormat parameters. Here, normalize is chosen when:

• The lexical preservation mode is set to automatic and the output format is ditaMarkup.

• 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 'outputFormat' and the 'preservationMode', as discussed in the main whitespace processing mode documentation.

The default value is automatic.

wordByWord

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.

characterByCharacter

Specifies whether to perform detailed character comparison or not.

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

The default value is false.

Table Comparison Configuration Parameters

These parameters control how tables are compared.

calsTableProcessing

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

invalidTableBehaviour

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

• compareAsXml Compare the table content as wellFormed 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.

removeRevAttributeRegex

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 addRevisionAtts property is true.

The default value is deltaxml-.*.

stepsConflictResolution

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

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

This parameter can take the following values:

• prefer-a Use the element name from the 'A' document to contain the compared entries.

• prefer-b Use the element name from the 'B' document to contain the compared entries.

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

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

The default value is preferB.

useIdsAsKeys

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.

strictTaskModel

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.

ignoreInlineFormatting

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

inlineFormattingElements

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

This parameter overrides the built in list of DITA inline elements. If the parameter ignoreInlineFormatting 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.

addInlineFormattingElements

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

Use this list to add to the value of inlineFormattingElements which you wish to be ignored when considering change processing.

Elements in this list are added to the set in inlineFormattingElements, before the set in removeInlineFormattingElements has been removed.

The default value is "" (empty).

removeInlineFormattingElements

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

Use this list to remove from the value of inlineFormattingElements 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 inlineFormattingElements, after the set in addInlineFormattingElements has been added.

The default value is "" (empty).

Element Moves Handling Parameters

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

detectMoves

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

moveSourceRevision

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

moveTargetRevision

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

removeMoveSource

Remove move source. This is by default disabled.

MathML Comparison Configuration Parameters

mathmlProcessing

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-grained changes. Because MathML attributes cannot 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 MathML validity is not a concern, changes may be represented at finer granularity.

The default value is true.

mathmlGranularity

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.

• detailed-adjacent 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

imageCompare

Specifies whether to compare images. By default, image comparison is enabled.

outputImageRefForm

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

svgProcessing

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.

svgGranularity

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

• adjacent Displays both SVG images side-by-side.

• detailedAdjacent Displays both SVG images side-by-side while also adding styling to highlight individual changes.

The default is detailedAdjacent.

inputASvgMarkupStyle

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.

inputBSvgMarkupStyle

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.

svgFallback

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

svgFallbackChangePercentage

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

invalidReferencedSvgBehaviour

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

svgZIndex

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

zIndexSvgMarkupStyle

Sets the Input Z-Index 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.

svgNumericTolerance

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

svgNumericToleranceValue

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.

validateInputs

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.

warningReportMode

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

This parameter can take the following values:

• message-report the recoverable errors and warnings as XSL messages, which are typically visible when the comparison is run from a commandLine terminal.

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

• comments Add the recoverable errors and warnings as comments.

• markup-add 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).

mapContextHref

When set to the nonEmpty 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 "" (empty).

mapCopyScope

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.

mapScanTopicsForReferences

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

modifiedAttributeMode

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 outputFormat. 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 attributeChange ('ac') namespace.

The default value is automatic.

unmarkedChangeMode

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

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 behavior and force particular outcomes, even if this outcome is not valid.

forceSpecialization

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.

outputEncodingDeclaration

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

Selecting the system special value has the effect of choosing the 'B' document's character encoding.

The default value is system.

topicPublicId

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 reSpecialize the result document even if the inputs were different types

The default value is "" (empty).

topicSystemId

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 respecialize the result document even if the inputs were different types

The default value is "" (empty).

xmlVersionDeclaration

Sets the version to use in the XML declaration.

Selecting the system special value has the effect of choosing the 'B' document's document's xmlVersion (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.