Configuration File Schema Guide

This guide provides a short description of each element and attribute defined in the XML schema for the DocBook Compare configuration file. A fuller description of the configuration file, along with the examples and an explanation of the main concepts can be found in the User Guide and associated documentation.

An occurrence indicator is used here for cases other than where a child element may occur once and only once. The occurrent indicators are descibed below:

[*] - Zero or more
[?] - Zero or once
[+] - One or more

Element Index

addInlineFormattingElements 27

additionalPhraseContainers 2

advancedBehaviour 8

advancedParameters 5

calsTableProcessing 39

common 17

comparisonParameters 6

configuration 1

detectMoves 37

enableXinclude 19

formattingElements 11

framemakerTcsTableChangeMode 48

grouping 44

htmlTableProcessing 40

ignoreInlineFormatting 28

imageCompare 31

imageComparison 12

indentOutput 45

inlineFormattingElements 29

invalidTableBehaviour 41

keyingMode 38

mathml 13

mathmlGranularity 35

mathmlProcessing 36

modifiedAttributeMode 23

otherComparisonParameters 14

outputEncodingDeclaration 20

outputFormat 46

outputImageRefFavourSourceDoc 32

outputImageRefForm 33

outputParameters 7

oxygenTcsDeletedSpaceMode 49

oxygenTcsVersion 50

parameters 3

preservationMode 47

removeInlineFormattingElements 30

selectingUnrepresentableChange 9

showImageChangesAtMediaobjectLevel 34

showNonPhraseChanges 4

standaloneDeclaration 21

tableComparison 15

textComparison 16

trackedChanges 18

trackedChangesAuthor 51

trackedChangesDate 52

unmarkedChangeMode 24

validateInputs 25

validation 10

warningReportMode 26

whitespaceProcessingMode 42

wordByWord 43

xmetalTcsTableChangeMode 53

xmlVersionDeclaration 22

Element Detail

Elements are listed in document-tree order, top-level elements first, then alphabetically:

Element: configuration 1

The root element for defining the configuration for DocBook Compare REST.

Contained by

/

Contains

Element	Description
additionalPhraseContainers	Sets the comma and/or space separated list of additional phrase elements using Clark notation
parameters	The root element for defining the configuration parameters for the comparison
showNonPhraseChanges	Sets whether to textually mark changes to text where phrase elements are not allowed

Element: additionalPhraseContainers 2

Sets the comma and/or space separated list of additional phrase elements using Clark notation.

Contained by

/ configuration

Contains

Type: xs:string

Element: parameters 3

The root element for defining the configuration parameters for the comparison.

Contained by

/ configuration

Contains

Element	Description
advancedParameters	The advanced settings parameters provide a finer level of control over the comparison, the output, and error reporting
comparisonParameters	These parameters control how the comparison is performed
outputParameters	These parameters enable the form of the output to be configured

Element: showNonPhraseChanges 4

Sets whether to textually mark changes to text where phrase elements are not allowed.

Contained by

/ configuration

Contains

Type: xs:boolean

Element: advancedParameters 5

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

Contained by

/ configuration / parameters

Contains

Element	Description
advancedBehaviour	Parameters used to override or force specific behaviours
selectingUnrepresentableChange	These parameters are used to specify how unrepresentable change can be handled
validation	Input validation and reporting

Element: comparisonParameters 6

These parameters control how the comparison is performed.

Contained by

/ configuration / parameters

Contains

Element	Description
formattingElements	These parameters control which DITA elements are marked as inline structural changes
imageComparison	Parameters managing image comparison
mathml	Parameters managing MathML
otherComparisonParameters	Settings that do not fit into other categories
tableComparison	These parameters control how tables are compared
textComparison	These parameters control how text is compared and whitespace handled

Element: outputParameters 7

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

Contained by

/ configuration / parameters

Contains

Element	Description
common	The output parameters that are either used to specify a specific output type or apply to all output types
trackedChanges	The tracked changes output format specific parameters provide a way of configuring tracked change output and editor/format specific output

Element: advancedBehaviour 8

Parameters used to override or force specific behaviours.

Contained by

/ configuration / parameters / advancedParameters

Contains

Element	Description
enableXinclude	If set to true the parser will process XIncludes while parsing the inputs
outputEncodingDeclaration	Sets the character encoding output to use in the XML declaration
standaloneDeclaration	This parameter no longer has any effect
xmlVersionDeclaration	Sets the version to use in the XML declaration

Element: selectingUnrepresentableChange 9

These parameters are used to specify how unrepresentable change can be handled.

Contained by

/ configuration / parameters / advancedParameters

Contains

Element	Description
modifiedAttributeMode	how modified attributes should be included in the output
unmarkedChangeMode	how to handle data that cannot contain difference markup

Element: validation 10

Input validation and reporting.

Contained by

/ configuration / parameters / advancedParameters

Contains

Element	Description
validateInputs	Specifies whether to validate input documents
warningReportMode	Sets the mode to use for reporting recoverable errors and warnings

Element: formattingElements 11

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

Contained by

/ configuration / parameters / comparisonParameters

Contains

Element	Description
addInlineFormattingElements	A comma and/or space separated list of inline formatting elements, which will be added to the value of the inline-formatting-elements parameter
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
inlineFormattingElements	Sets the comma and/or space separated list of inline formatting elements
removeInlineFormattingElements	A comma and/or space separated list of inline formatting elements, which will be removed from the value of the inline-formatting-elements parameter

Element: imageComparison 12

Parameters managing image comparison.

Contained by

/ configuration / parameters / comparisonParameters

Contains

Element	Description
imageCompare	Specifies whether to compare images
outputImageRefFavourSourceDoc	If image-compare is set to true, this parameter controls which imagedata fileref attribute, from A or B is use to derive the result fileref value when the image has not changed
outputImageRefForm	If image-compare is set to true, this parameter controls the form output for fileref attributes of imagedata elements
showImageChangesAtMediaobjectLevel	If image-compare is set to true and determines that images have changed, show the changes as changes to the containing mediaobjects

Element: mathml 13

Parameters managing MathML

Contained by

/ configuration / parameters / comparisonParameters

Contains

Element	Description
mathmlGranularity	Specifies the granularity at which the differences between the two MathML expressions will be represented
mathmlProcessing	Specifies whether to apply MathML processing

Element: otherComparisonParameters 14

Settings that do not fit into other categories.

Contained by

/ configuration / parameters / comparisonParameters

Contains

Element	Description
detectMoves	Sets to detect and handle element moves
keyingMode	Sets the mode to use for adding keys to the input documents

Element: tableComparison 15

These parameters control how tables are compared.

Contained by

/ configuration / parameters / comparisonParameters

Contains

Element	Description
calsTableProcessing	Specifies whether to apply CALS table processing
htmlTableProcessing	Specifies whether to apply HTML table/DITA simpletable processing
invalidTableBehaviour	This parameter declares what type of processing should be used for those tables that are marked as invalid

Element: textComparison 16

These parameters control how text is compared and whitespace handled.

Contained by

/ configuration / parameters / comparisonParameters

Contains

Element	Description
whitespaceProcessingMode	Specifies how to handle whitespace changes
wordByWord	Specifies whether to perform detailed text comparison or not

Element: common 17

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

Contained by

/ configuration / parameters / outputParameters

Contains

Element	Description
grouping	Specifies whether adjacent changes (insertions or deletions) should be grouped into a single insertion and/or deletion block
indentOutput	Sets whether the result should be indented
outputFormat	Specifies what type of output is produced
preservationMode	Sets the mode to use for preserving original data

Element: trackedChanges 18

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

Contained by

/ configuration / parameters / outputParameters

Contains

Element	Description
framemakerTcsTableChangeMode	Specifies how changes in tables should be tracked
oxygenTcsDeletedSpaceMode	Specifies how deleted spaces should be handled
oxygenTcsVersion	Specifies the version of Oxygen editor used to display, accept and reject the tracked changes
trackedChangesAuthor	Specifies the author name that is embedded into the generated insertion and deletion processing instruction
trackedChangesDate	Specifies the time-stamp that is embedded into the generated insertion and deletion processing instruction
xmetalTcsTableChangeMode	Specifies how changes in tables should be tracked

Element: enableXinclude 19

If set to true the parser will process XIncludes while parsing the inputs.

Contained by

/ configuration / parameters / advancedParameters / advancedBehaviour

Contains

Type: xs:boolean

Element: outputEncodingDeclaration 20

Sets the character encoding output to use in the XML declaration.

Contained by

/ configuration / parameters / advancedParameters / advancedBehaviour

Contains

Type: xs:string

Element: standaloneDeclaration 21

This parameter no longer has any effect.

Preserving the standalone declaration is not supported, due to incompatibilities in the underpinning parsing and serialisation technologies.

Contained by

/ configuration / parameters / advancedParameters / advancedBehaviour

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

yes: Ensure the standalone attribute is set to 'yes' in the output XML declaration.
no: Ensure the standalone attribute is set to 'no' in the output XML declaration.
omit: Ensure there is no standalone attribute in the output XML declaration.
system: Deprecated: has the same affect as the omit value.

Element: xmlVersionDeclaration 22

Sets the version to use in the XML declaration.

Contained by

/ configuration / parameters / advancedParameters / advancedBehaviour

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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

Element: modifiedAttributeMode 23

how modified attributes should be included in the output.

Contained by

/ configuration / parameters / advancedParameters / selectingUnrepresentableChange

Contains

Type: xs:string

Element: unmarkedChangeMode 24

how to handle data that cannot contain difference markup.

Contained by

/ configuration / parameters / advancedParameters / selectingUnrepresentableChange

Contains

Type: xs:string

Element: validateInputs 25

Specifies whether to validate input documents.

Contained by

/ configuration / parameters / advancedParameters / validation

Contains

Type: xs:boolean

Element: warningReportMode 26

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

Contained by

/ configuration / parameters / advancedParameters / validation

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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.

Element: addInlineFormattingElements 27

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

Contained by

/ configuration / parameters / comparisonParameters / formattingElements

Contains

Type: xs:string

Element: ignoreInlineFormatting 28

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.

Contained by

/ configuration / parameters / comparisonParameters / formattingElements

Contains

Type: xs:boolean

Element: inlineFormattingElements 29

Sets the comma and/or space separated list of inline formatting elements.

Contained by

/ configuration / parameters / comparisonParameters / formattingElements

Contains

Type: xs:string

Element: removeInlineFormattingElements 30

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

Contained by

/ configuration / parameters / comparisonParameters / formattingElements

Contains

Type: xs:string

Element: imageCompare 31

Specifies whether to compare images.

Contained by

/ configuration / parameters / comparisonParameters / imageComparison

Contains

Type: xs:boolean

Element: outputImageRefFavourSourceDoc 32

If image-compare is set to true, this parameter controls which imagedata fileref attribute, from A or B is use to derive the result fileref value when the image has not changed

Contained by

/ configuration / parameters / comparisonParameters / imageComparison

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

A: The value from the 'A' source document will be used
B: The value from the 'B' source document will be used.

Element: outputImageRefForm 33

If image-compare is set to true, this parameter controls the form output for fileref attributes of imagedata elements

Contained by

/ configuration / parameters / comparisonParameters / imageComparison

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

absolute: the value will be the absolute location used to calculate whether the image has changed.
source: the value will be as it appears in the source A or B document.

Element: showImageChangesAtMediaobjectLevel 34

If image-compare is set to true and determines that images have changed, show the changes as changes to the containing mediaobjects.

Contained by

/ configuration / parameters / comparisonParameters / imageComparison

Contains

Type: xs:boolean

Element: mathmlGranularity 35

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

Contained by

/ configuration / parameters / comparisonParameters / mathml

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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.

Element: mathmlProcessing 36

Specifies whether to apply MathML processing.

Contained by

/ configuration / parameters / comparisonParameters / mathml

Contains

Type: xs:boolean

Element: detectMoves 37

Sets to detect and handle element moves.

Contained by

/ configuration / parameters / comparisonParameters / otherComparisonParameters

Contains

Type: xs:boolean

Element: keyingMode 38

Sets the mode to use for adding keys to the input documents.

Contained by

/ configuration / parameters / comparisonParameters / otherComparisonParameters

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

preserve: Use existing deltaxml:key attributes from the input (and nothing else)
useKeyThenId: Use a deltaxml:key attribute if present, otherwise use an id attribute if present
useKeyThenCondition: Use a deltaxml:key attribute if present, otherwise use a condition attribute if present
useId: Use an id attribute if present. Otherwise, do not use a key
useCondition: Use a condition attribute if present. Otherwise, do not use a key
remove: Remove all existing deltaxml:key attributes and do not add any others

Element: calsTableProcessing 39

Specifies whether to apply CALS table processing.

Contained by

/ configuration / parameters / comparisonParameters / tableComparison

Contains

Type: xs:boolean

Element: htmlTableProcessing 40

Specifies whether to apply HTML table/DITA simpletable processing.

Contained by

/ configuration / parameters / comparisonParameters / tableComparison

Contains

Type: xs:boolean

Element: invalidTableBehaviour 41

This parameter declares what type of processing should be used for those tables that are marked as invalid.

Contained by

/ configuration / parameters / comparisonParameters / tableComparison

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

fail: Throw an exception.
propagateUp: Propagate the changes to the table-level.
compareAsXml: Compare the table content as well-formed XML.

Element: whitespaceProcessingMode 42

Specifies how to handle whitespace changes.

Contained by

/ configuration / parameters / comparisonParameters / textComparison

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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.

Element: wordByWord 43

Specifies whether to perform detailed text comparison or not.

Contained by

/ configuration / parameters / comparisonParameters / textComparison

Contains

Type: xs:boolean

Element: grouping 44

Specifies whether adjacent changes (insertions or deletions) should be grouped into a single insertion and/or deletion block.

Contained by

/ configuration / parameters / outputParameters / common

Contains

Type: xs:boolean

Element: indentOutput 45

Sets whether the result should be indented.

Contained by

/ configuration / parameters / outputParameters / common

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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

Element: outputFormat 46

Specifies what type of output is produced.

Contained by

/ configuration / parameters / outputParameters / common

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

docbook-markup: Ignore differences in whitespace, unless they occur within a CDATA section (or are explicitly preserved).
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.

Element: preservationMode 47

Sets the mode to use for preserving original data.

Contained by

/ configuration / parameters / outputParameters / common

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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.

Element: framemakerTcsTableChangeMode 48

Specifies how changes in tables should be tracked.

Contained by

/ configuration / parameters / outputParameters / trackedChanges

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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.

Element: oxygenTcsDeletedSpaceMode 49

Specifies how deleted spaces should be handled.

Contained by

/ configuration / parameters / outputParameters / trackedChanges

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

automatic: Chooses the delete space processing mode based on the declared oxygen-tcs-version parameter.
normlize: Changes in rows and cells are pushed up to the table level.
keep: changes in a table are ignored.

Element: oxygenTcsVersion 50

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

Contained by

/ configuration / parameters / outputParameters / trackedChanges

Contains

Type: xs:float

Element: trackedChangesAuthor 51

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

Contained by

/ configuration / parameters / outputParameters / trackedChanges

Contains

Type: xs:string

Element: trackedChangesDate 52

Specifies the time-stamp that is embedded into the generated insertion and deletion processing instruction.

Contained by

/ configuration / parameters / outputParameters / trackedChanges

Contains

Type: xs:string

Element: xmetalTcsTableChangeMode 53

Specifies how changes in tables should be tracked.

Contained by

/ configuration / parameters / outputParameters / trackedChanges

Contains

Attribute

Type

Description

mode

[enum]

Permitted values / descriptions:

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.

(This documentation was auto-generated from the XML Schema for the DocBook Compare configuration file.)