Formatting Elements With Rule Processing Sample
Introduction
DITA Merge allows users to mark elements in the DITA inputs as formatting elements. For these elements, the merge operation can focus on textual changes rather than structural changes. For further information, seeFormatting Elements Sampleand differentrepresentations for formatting element changes. DITA Merge also provides capability to automatically resolve "simple changes" by applying rule processing. For more information about rule processing, seeRule processing guide.
This sample aims to demonstrate the behaviour of formatting elements when rule processing is enabled.
Applying rules to formatting elements
When the rule processing is enabled, DITA Merge accepts simple adds, deletes and modification. All of these rules are applied to attributes, elements and their contents. However, when it comes to formatting elements, the rule processing is applied to formatting element tags instead of their contents. The formatting elements tags are usually added or deleted around the content in the inputs. This means that that there is no possibility of modification or conflict in case of formatting element tag changes. So we can categorise formatting element tags changes as:
Addition of formatting element tags : When rule processing is enabled, the addition is accepted. In other words, the formatting tags are resolved and kept in the result.
Deletion of formatting element tags : When rule processing is enabled, the deletion is accepted. In other words, the formatting tags are removed.
Addition of formatting element introducing an overlap: If a document version adds a formatting element which introduces an overlap with another formatting element from other document version, then it is not considered as a simple change. These kind of changes are not resolved during rule processing.
The default behaviour of rule processing which accepts simple adds and deletes can be changed by using methods setDisplaySimpleAdds and setDisplaySimpleDeletes on the RuleConfiguration object. The method setDisplayChangesInvolving can be used with formatting elements to show added or deleted formatting elements by a particular version. Also, a method setDisplayFormatChangesIn can be used to show formatting changes inside an element.
Example
To illustrate how DITA Merge works with formatting elements when rule processing is enabled, we will examine the following three versions, 'A', 'B' and 'C' of a simple document. Where 'A' is the common ancestor. In the following versions, the 'b' formatting has been added in the first 'p' by 'B' and 'C', whereas 'i' formatting has been deleted by 'C' in the second 'p'.
A
<topic id="topic_vtw_jfs_33b">
<title></title>
<body>
<p>Example of formatting addition around the word.</p>
<p>Example of formatting deletion around the <i>word</i>.</p>
</body>
</topic>B
<topic id="topic_vtw_jfs_33b">
<title></title>
<body>
<p>Example of formatting addition around the <b>word</b>.</p>
<p>Example of formatting deletion around the <i>word</i>.</p>
</body>
</topic>C
<topic id="topic_vtw_jfs_33b">
<title></title>
<body>
<p>Example of formatting addition around the <b>word</b>.</p>
<p>Example of formatting deletion around the word.</p>
</body>
</topic>Results
The following result is generated with rule processing disabled.
DeltaV2.1 Result
<topic deltaxml:version="2.1" deltaxml:deltaV2="A!=B!=C">
<title deltaxml:deltaV2="A=B=C"/>
<body deltaxml:deltaV2="A!=B!=C">
<p deltaxml:deltaV2="A!=B=C">Example of formatting addition around the <b
deltaxml:deltaTag="B,C" deltaxml:deltaV2="A!=B=C">word</b>.</p>
<p deltaxml:deltaV2="A=B!=C">Example of formatting deletion around the <i
deltaxml:deltaTag="A,B" deltaxml:deltaV2="A=B!=C">word</i>.</p>
</body>
</topic>
The following result is generated with rule processing enabled. In this result, the added 'b' element has been accepted and deleted 'i' element has been removed.
Rule Processed DeltaV2.1 Result
<topic deltaxml:version="2.1" deltaxml:deltaV2="A=B=C">
<title/>
<body>
<p>Example of formatting addition around the <b>word</b>.</p>
<p>Example of formatting deletion around the word.</p>
</body>
</topic>The following result is also generated with rule processing enabled. But this time the displayChangesInvolving property is set to 'B'. In this result, the addition of 'b' element is not resolved as it involves B, however the deletion of 'i' element (which involves 'C') is resolved.
Rule Processed DeltaV2.1 Result- Display Changes Involving Version B
<topic deltaxml:version="2.1" deltaxml:deltaV2="A!=B=C">
<title deltaxml:deltaV2="A=B=C"/>
<body deltaxml:deltaV2="A!=B=C">
<p deltaxml:deltaV2="A!=B=C">Example of formatting addition around the <b
deltaxml:deltaTag="B,C" deltaxml:deltaV2="A!=B=C">word</b>.</p>
<p deltaxml:deltaV2="A=B=C">Example of formatting deletion around the word.</p>
</body>
</topic>The following result is also generated with rule processing enabled, but this time the displayFormatChangesIn property is set to the XPath '//*[local-name() eq 'p']' which selects all 'p' elements in the XML. The result therefore displays the changes to formatting elements in all 'p' elements.
Extracting DeltaV2.1 format output with rule processing - Display Formatting Changes In all paragraphs
<topic deltaxml:version="2.1" deltaxml:deltaV2="A!=B!=C">
<title deltaxml:deltaV2="A=B=C"/>
<body deltaxml:deltaV2="A!=B!=C">
<p deltaxml:deltaV2="A!=B=C">Example of formatting addition around the <b
deltaxml:deltaTag="B,C" deltaxml:deltaV2="A!=B=C">word</b>.</p>
<p deltaxml:deltaV2="A=B!=C">Example of formatting deletion around the <i
deltaxml:deltaTag="A,B" deltaxml:deltaV2="A=B!=C">word</i>.</p>
</body>
</topic>Implementation
The sample is implemented in the main method of a single Java class, FormattingElementsWithRuleProcessing.java . This class contains comments and System.out message text that explains usage of the DITA Merge Java API for this sample.
Running the Sample
To run this sample, all the files you need together with instructions are available on Bitbucket