Merge Formatting Elements Sample

In XML-based documentation systems, some elements are concerned with the structure of a document and others exist purely to suggest the intended styling of the final document. These latter elements are referred to as Formatting Elements. The set of formatting elements varies between documentation systems. For example, to request bold styling DITA provides <b/> and DocBook provides <emphasis/>. Merge allows the user to specify the set of elements to be treated as formatting elements.

The formatting element functionality allows users to focus on either purely textual content differences or styling differences. When enabled, Merge provides additional output formats showing different views of the changes. See Merge — Formatting Element Representations for details of the available output types.

Example Input Files and Configuration

Input Files

The following four versions of a simple document illustrate how Merge handles formatting element changes. These might be multiple edits of the same content over time or by different authors.

Ancestor Version "A" — no formatting:

XML

<document>
  <para>This paragraph will have words in bold in the following version.</para>
</document>

Modified Version "B" — no text changes, but bold formatting added:

XML

<document>
  <para>This paragraph will have <bold>words in bold</bold> in the following version.</para>
</document>

Modified Version "C" — text changes and styling changes; bold removed, one word italicised:

XML

<document>
  <para>This paragraph will have words in <italic>italics</italic> in this version.</para>
</document>

Modified Version "D" — multiple styling changes; italics nested inside underline, text unchanged from "C":

XML

<document>
  <para>This paragraph will have <underline>words in <italic>italics</italic></underline> in this version.</para>
</document>

Configuring Formatting Elements

Specify which elements to treat as formatting elements using a stylesheet such as mark-formatting.xsl, which matches element names and adds deltaxml:format="true". For DITA, a typical list might be:

"b|i|sup|sub|tt|u|line-through|overline"

The stylesheet must be added to the PRE_FLATTENING extension point using the Java API:

Java

// Specify which elements to consider as formatting
FilterStepHelper fsh = merge.getFilterStepHelper();
FilterChain fc = fsh.newSingleStepFilterChain(new File(dataFolder, "mark-formatting.xsl"), "mark-formatting");
merge.setExtensionPoint(ExtensionPoint.PRE_FLATTENING, fc);

Then set the required output type using FormattingOutputType:

Java

merge.setFormattingOutputType(FormattingOutputType.DELTA_V_2_1);

Default Output (No Formatting Element Support)

Without formatting elements enabled, the DeltaV2.1 output for the sample inputs is:

XML

<document xmlns:deltaxml="http://www.deltaxml.com/ns/well-formed-delta-v1"
  deltaxml:version-order="A, B, C, D" deltaxml:content-type="merge-concurrent"
  deltaxml:version="2.0" deltaxml:deltaV2="A!=B!=C!=D">
  <para deltaxml:deltaV2="A!=B!=C!=D">This paragraph will have
    <deltaxml:textGroup deltaxml:deltaV2="A=C!=B">
      <deltaxml:text deltaxml:deltaV2="A=C">words</deltaxml:text>
      <deltaxml:text deltaxml:deltaV2="B"> </deltaxml:text>
    </deltaxml:textGroup>
    <bold deltaxml:deltaV2="B">words in bold</bold>
    <deltaxml:textGroup deltaxml:deltaV2="D">
      <deltaxml:text deltaxml:deltaV2="D"> </deltaxml:text>
    </deltaxml:textGroup>
    <underline deltaxml:deltaV2="D">words in <italic>italics</italic></underline>
    <deltaxml:textGroup deltaxml:deltaV2="A!=C!=D">
      <deltaxml:text deltaxml:deltaV2="A"> in bold</deltaxml:text>
      <deltaxml:text deltaxml:deltaV2="C"> in </deltaxml:text>
      <deltaxml:text deltaxml:deltaV2="D"> in this</deltaxml:text>
    </deltaxml:textGroup>
    <italic deltaxml:deltaV2="C">italics</italic>
    <deltaxml:textGroup deltaxml:deltaV2="A=B!=C">
      <deltaxml:text deltaxml:deltaV2="A=B"> in the following</deltaxml:text>
      <deltaxml:text deltaxml:deltaV2="C"> in this</deltaxml:text>
    </deltaxml:textGroup> version.</para>
</document>

Formatting Elements DeltaV2.1 Output

With formatting elements enabled, the DeltaV2.1 output is more compact and highlights the formatting element hierarchy with less duplication of changed text:

XML

<document xmlns:deltaxml="http://www.deltaxml.com/ns/well-formed-delta-v1"
  deltaxml:version-order="A, B, C, D" deltaxml:content-type="merge-concurrent"
  deltaxml:version="2.1" deltaxml:deltaV2="A!=B!=C!=D">
  <para deltaxml:deltaV2="A!=B!=C!=D">This paragraph will have
    <bold deltaxml:deltaTag="B" deltaxml:deltaV2="A!=B!=C!=D">
      <underline deltaxml:deltaTag="D" deltaxml:deltaV2="A=B!=C!=D">words in
        <italic deltaxml:deltaTag="C,D" deltaxml:deltaV2="A=B!=C=D">
          <deltaxml:textGroup deltaxml:deltaV2="A=B!=C=D">
            <deltaxml:text deltaxml:deltaV2="A=B">bold</deltaxml:text>
            <deltaxml:text deltaxml:deltaV2="C=D">italics</deltaxml:text>
          </deltaxml:textGroup>
        </italic>
      </underline>
    </bold> in
    <deltaxml:textGroup deltaxml:deltaV2="A=B!=C=D">
      <deltaxml:text deltaxml:deltaV2="A=B">the following</deltaxml:text>
      <deltaxml:text deltaxml:deltaV2="C=D">this</deltaxml:text>
    </deltaxml:textGroup> version.
  </para>
</document>

Content Group Output

The CONTENT_GROUP output type produces contentGroup elements containing both text children (text changes only, ignoring formatting) and content children (text and formatting changes combined):

XML

<document xmlns:deltaxml="http://www.deltaxml.com/ns/well-formed-delta-v1"
  deltaxml:version-order="A, B, C, D" deltaxml:content-type="merge-concurrent"
  deltaxml:version="2.0" deltaxml:deltaV2="A!=B!=C!=D">
  <para deltaxml:deltaV2="A!=B!=C!=D">This paragraph will have
    <deltaxml:contentGroup deltaxml:wordDelta="A=B!=C=D" deltaxml:deltaV2="A!=B!=C!=D">
      <deltaxml:text deltaxml:deltaV2="A=B">words in bold</deltaxml:text>
      <deltaxml:text deltaxml:deltaV2="C=D">words in italics</deltaxml:text>
      <deltaxml:content deltaxml:deltaV2="A">words in bold</deltaxml:content>
      <deltaxml:content deltaxml:deltaV2="B"><bold>words in bold</bold></deltaxml:content>
      <deltaxml:content deltaxml:deltaV2="C">words in <italic>italics</italic></deltaxml:content>
      <deltaxml:content deltaxml:deltaV2="D"><underline>words in <italic>italics</italic></underline></deltaxml:content>
    </deltaxml:contentGroup> in
    <deltaxml:textGroup deltaxml:deltaV2="A=B!=C=D">
      <deltaxml:text deltaxml:deltaV2="A=B">the following</deltaxml:text>
      <deltaxml:text deltaxml:deltaV2="C=D">this</deltaxml:text>
    </deltaxml:textGroup> version.
  </para>
</document>

Implementation

The sample is implemented in the main method of FormattingElements.java:

Create File objects for sample inputs.
Instantiate the merge object using ConcurrentMerge or SequentialMerge.
Set the ancestor file (for ConcurrentMerge) with ConcurrentMerge.setAncestor.
Add input versions using ConcurrentMerge.addVersion or SequentialMerge.addVersion.
Set the formatting output type to DELTA_V_2_1 or CONTENT_GROUP.
Call extractAll to produce the DeltaV2 merge result.

Running the Sample

Full source and instructions are available on Bitbucket.