Skip to main content
Skip table of contents

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

 

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
ElementDescription
parameters The root element for defining the configuration parameters for the comparison

Element: parameters 2

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

Contained by
Contains
ElementDescription
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: advancedParameters 3

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

Contained by
Contains
ElementDescription
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 4

These parameters control how the comparison is performed.

Contained by
Contains
ElementDescription
alignment Settings that affect the alignment/matching of documents
formattingElements These parameters control which DocBook elements are marked as inline structural changes
imageComparison Parameters managing image comparison
mathml Parameters managing MathML
moves Settings that affect the alignment/matching of documents
svgComparison These parameters control how SVG changes are displayed
tableComparison These parameters control how tables are compared
textComparison These parameters control how text is compared and whitespace handled

Element: outputParameters 5

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

Contained by
Contains
ElementDescription
common The output parameters that are either used to specify a specific output type or apply to all output types
phraseChanges Settings that affect the behaviour of displaying text changes
trackedChanges The tracked changes output format specific parameters provide a way of configuring tracked change output and editor/format specific output

Element: advancedBehaviour 6

Parameters used to override or force specific behaviours.

Contained by
Contains
ElementDescription
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 7

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

Contained by
Contains
ElementDescription
modifiedAttributeMode how modified attributes should be included in the output
unmarkedChangeMode how to handle data that cannot contain difference markup

Element: validation 8

Input validation and reporting.

Contained by
Contains
ElementDescription
validateInputs Specifies whether to validate input documents
warningReportMode Sets the mode to use for reporting recoverable errors and warnings

Element: alignment 9

Settings that affect the alignment/matching of documents.

Contained by
Contains
ElementDescription
detectMoves Setting to detect and handle element moves
keyingMode Sets the mode to use for adding keys to the input documents

Element: formattingElements 10

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

Contained by
Contains
ElementDescription
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 DocBook 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 11

Parameters managing image comparison.

Contained by
Contains
ElementDescription
imageCompare Specifies whether to compare images
mediaObjectParentsList Sets the comma and/or space separated list of media object parents using Clark notation
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
showImageChangesAtMediaObjectParentLevel If image-compare is set to true and determines that images have changed, show the changes as changes to the parent element of mediaobject

Element: mathml 12

Parameters managing MathML

Contained by
Contains
ElementDescription
mathmlGranularity Specifies the granularity at which the differences between the two MathML expressions will be represented
mathmlProcessing Specifies whether to apply MathML processing

Element: moves 13

Settings that affect the alignment/matching of documents.

Contained by
Contains
ElementDescription
detectMoves Setting to detect and handle element moves
removeMoveSource Setting to remove source element moves

Element: svgComparison 14

These parameters control how SVG changes are displayed.

Contained by
Contains
ElementDescription
InputASVGMarkupStyle sets the A input markup colour
InputBSVGMarkupStyle sets the B input markup colour
SVGFallback Fallback to the ADJACENT result if alignment is below the defined threshold (set by fallbackChangePercentage)
SVGFallbackChangePercentage Defines the threshold at which fallback occurs if svgFallback is true
SVGNumericTolerance enables svg numeric tolerance, changes less than numericToleranceValue are ignored
SVGNumericToleranceValue Defines the threshold value for numeric tolerance
SVGZIndex enables representation of Z index changes
ZIndexSVGMarkupStyle sets the markup colour for representation of Z index changes
compareSVG Whether an SVG comparison should be carried out
svgComparisonGranularity Specifies how to display SVG changes

Element: tableComparison 15

These parameters control how tables are compared.

Contained by
Contains
ElementDescription
calsTableProcessing Specifies whether to apply CALS table processing
htmlTableProcessing Specifies whether to apply HTML table 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
Contains
ElementDescription
characterByCharacter Specifies whether to perform a character by character comparison or not
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
Contains
ElementDescription
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: phraseChanges 18

Settings that affect the behaviour of displaying text changes.

Contained by
Contains
ElementDescription
additionalPhraseContainers Sets the comma and/or space separated list of additional phrase elements using Clark notation
showNonPhraseChanges Sets whether to textually mark changes to text where phrase elements are not allowed

Element: trackedChanges 19

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

Contained by
Contains
ElementDescription
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 20

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

Contained by
Contains

Type: xs:boolean

Element: outputEncodingDeclaration 21

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

Contained by
Contains

Type: xs:string

Element: standaloneDeclaration 22

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
Contains
AttributeTypeDescription
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 23

Sets the version to use in the XML declaration.

Contained by
Contains
AttributeTypeDescription
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 24

how modified attributes should be included in the output.

Contained by
Contains

Type: xs:string

Element: unmarkedChangeMode 25

how to handle data that cannot contain difference markup.

Contained by
Contains

Type: xs:string

Element: validateInputs 26

Specifies whether to validate input documents.

Contained by
Contains

Type: xs:boolean

Element: warningReportMode 27

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

Contained by
Contains
AttributeTypeDescription
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: detectMoves 28

Setting to detect and handle element moves.

Contained by
Contains

Type: xs:boolean

Element: keyingMode 29

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

Contained by
Contains
AttributeTypeDescription
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: addInlineFormattingElements 30

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
Contains

Type: xs:string

Element: ignoreInlineFormatting 31

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

Contained by
Contains

Type: xs:boolean

Element: inlineFormattingElements 32

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

Contained by
Contains

Type: xs:string

Element: removeInlineFormattingElements 33

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
Contains

Type: xs:string

Element: imageCompare 34

Specifies whether to compare images.

Contained by
Contains

Type: xs:boolean

Element: mediaObjectParentsList 35

Sets the comma and/or space separated list of media object parents using Clark notation.

Only active when showImageChangesAtMediaObjectParentLevel is set to true..

Contained by
Contains

Type: xs:string

Element: outputImageRefFavourSourceDoc 36

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
Contains
AttributeTypeDescription
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 37

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

Contained by
Contains
AttributeTypeDescription
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 38

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

Contained by
Contains

Type: xs:boolean

Element: showImageChangesAtMediaObjectParentLevel 39

If image-compare is set to true and determines that images have changed, show the changes as changes to the parent element of mediaobject.

Contained by
Contains

Type: xs:boolean

Element: mathmlGranularity 40

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

Contained by
Contains
AttributeTypeDescription
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 41

Specifies whether to apply MathML processing.

Contained by
Contains

Type: xs:boolean

Element: removeMoveSource 42

Setting to remove source element moves.

Contained by
Contains

Type: xs:boolean

Element: InputASVGMarkupStyle 43

sets the A input markup colour.

Default is red

Contained by
Contains

Type: xs:string

Element: InputBSVGMarkupStyle 44

sets the B input markup colour.

Default is green

Contained by
Contains

Type: xs:string

Element: SVGFallback 45

Fallback to the ADJACENT result if alignment is below the defined threshold (set by fallbackChangePercentage).

Contained by
Contains

Type: xs:boolean

Element: SVGFallbackChangePercentage 46

Defines the threshold at which fallback occurs if svgFallback is true

Contained by
Contains

Type: xs:double

Element: SVGNumericTolerance 47

enables svg numeric tolerance, changes less than numericToleranceValue are ignored

Contained by
Contains

Type: xs:boolean

Element: SVGNumericToleranceValue 48

Defines the threshold value for numeric tolerance.

Default is '1%', can also be provided as numeric value (in pixels)

Contained by
Contains

Type: xs:string

Element: SVGZIndex 49

enables representation of Z index changes

Contained by
Contains

Type: xs:boolean

Element: ZIndexSVGMarkupStyle 50

sets the markup colour for representation of Z index changes.

Default is purple.

Contained by
Contains

Type: xs:string

Element: compareSVG 51

Whether an SVG comparison should be carried out.

Contained by
Contains

Type: xs:boolean

Element: svgComparisonGranularity 52

Specifies how to display SVG changes.

Contained by
Contains
AttributeTypeDescription
mode[enum]

Permitted values / descriptions:


adjacent
Reports the differences to the SVG by repeating A and B SVG inputs adjacent to each other.
detailed-adjecent

Element: calsTableProcessing 53

Specifies whether to apply CALS table processing.

Contained by
Contains

Type: xs:boolean

Element: htmlTableProcessing 54

Specifies whether to apply HTML table processing.

Contained by
Contains

Type: xs:boolean

Element: invalidTableBehaviour 55

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

Contained by
Contains
AttributeTypeDescription
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: characterByCharacter 56

Specifies whether to perform a character by character comparison or not.

Contained by
Contains

Type: xs:boolean

Element: whitespaceProcessingMode 57

Specifies how to handle whitespace changes.

Contained by
Contains
AttributeTypeDescription
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 58

Specifies whether to perform detailed text comparison or not.

Contained by
Contains

Type: xs:boolean

Element: grouping 59

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

Contained by
Contains

Type: xs:boolean

Element: indentOutput 60

Sets whether the result should be indented.

Contained by
Contains
AttributeTypeDescription
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 61

Specifies what type of output is produced.

Contained by
Contains
AttributeTypeDescription
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 62

Sets the mode to use for preserving original data.

Contained by
Contains
AttributeTypeDescription
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: additionalPhraseContainers 63

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

Contained by
Contains

Type: xs:string

Element: showNonPhraseChanges 64

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

Contained by
Contains

Type: xs:boolean

Element: framemakerTcsTableChangeMode 65

Specifies how changes in tables should be tracked.

Contained by
Contains
AttributeTypeDescription
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 66

Specifies how deleted spaces should be handled.

Contained by
Contains
AttributeTypeDescription
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 67

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

Contained by
Contains

Type: xs:float

Element: trackedChangesAuthor 68

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

Contained by
Contains

Type: xs:string

Element: trackedChangesDate 69

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

Contained by
Contains

Type: xs:string

Element: xmetalTcsTableChangeMode 70

Specifies how changes in tables should be tracked.

Contained by
Contains
AttributeTypeDescription
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.)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.