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, see Formatting Elements Sample and different representations for formatting element changes. DITA Merge also provides capability to automatically resolve "simple changes" by applying rule processing. For more information about rule processing, see Rule processing guide.
This sample aims to demonstrate the behaviour of formatting elements when rule processing is enabled.
2. 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.
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'.
The following result is generated with rule processing disabled.
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.
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.
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.
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.
6. Running the Sample
To run this sample, all the files you need together with instructions are available on Bitbucket