Package com.deltaxml.core.config

Class ResultReadabilityOptions

java.lang.Object
com.deltaxml.core.config.ResultReadabilityOptions
public class ResultReadabilityOptions extends Object

Sets options to change the granularity and ordering of changes in the result in order to improve readability.

The underlying comparison engine attempts to produce a result based on the Levenshtein distance between the inputs. While this will produce a mathematically optimal result, when looking at individual word changes in a block of text, the results produced are not always very readable as they can appear to be a mix of added, deleted and unchanged items. This configuration object can be used to make the result more readable using a variety of techniques, including:

  • Element splitting This involves splitting a modified element that contains text when the amount of text that is actually common/unchanged fall below a given percentage of the total content
  • Orphaned word detection This involves detecting cases where unchanged words lie within a larger block of modified text. This often occurs when common words such as 'the', 'and', 'a' etc are matched together in otherwise unrelated sentences. When these unchanged words are detected, they are treated as if they have been deleted and added again in order to make the larger change much more readable.
  • Change gathering This can have an effect at all levels of the XML tree. When sibling element/text is a mix of added and deleted content, it can be reordered to show, for example, all deleted content followed by all added content.

Changes to whitespace within a document can be insignificant, such as when editors automatically add line wrapping and indentation within a DITA, DocBook, or HTML paragraph. In these cases, it would be useful if changes in whitespace are not reported. This can be achieved in a number of ways, including: normalizing the whitespace in the inputs; and identifying and then ignoring modified whitespace in the raw comparison output. Here whitespace, at a given point in the document, is considered to be modified if, and only if, both documents have some whitespace at this point which differs.

Note: if there are subtrees in a document where whitespace change is important this can be identified by adding the standard XML xml:space="preserve" attribute to the top-element of the subtree, in the input filtering. Conversely, it is possible to specify that the whitespace within a subtree does not need to be preserved by adding the xml:space="default" attribute to the top-element of that subtree, which is the implicit setting.

Since:
7.0
See Also:

  • Constructor Details

  • Method Details

    • setElementSplittingEnabled

      public void setElementSplittingEnabled(boolean enabled)

      Sets whether modified elements containing text should be split when the amount of unchanged text falls below a given percentage.

      The percentage at which this behaviour is triggered can be set using setElementSplittingThreshold(int)

      Parameters:
      enabled - whether or not to enable element splitting
      See Also:

    • isElementSplittingEnabled

      public boolean isElementSplittingEnabled()

      States whether modified elements containing text are split when the amount of unchanged text falls below a given percentage.

      Returns:
      a boolean stating whether the splitting behaviour is enabled or not

    • setElementSplittingThreshold

      public void setElementSplittingThreshold(int percentage) throws IllegalArgumentException

      Sets the percentage of unchanged text present in a modified element below which the element will be split.

      Parameters:
      percentage - an integer in the range 0-100 specifying the percentage of unchanged text
      Throws:
      IllegalArgumentException - if the supplied parameter is not in the range 0-100

    • getElementSplittingThreshold

      public int getElementSplittingThreshold()

      Returns the percentage of unchanged text present in a modified element below which the element will be split.

      Returns:
      an integer in the range 0-100 specifying the percentage of unchanged text

    • setElementSplittingDebug

      public void setElementSplittingDebug(boolean debug)

      Sets whether the element splitting filter should output internal debug information.

      The internal debug output is passed using <xsl:message/>. This is typically passed to std.out but this can be changed my configuring the relevant Saxon Configuration object.

      Parameters:
      debug - whether the element splitting filter should output internal debug information
      See Also:
      • Configuration.setStandardErrorOutput(java.io.PrintStream)

    • isElementSplittingDebug

      public boolean isElementSplittingDebug()

      States whether the element splitting filter is set to output internal debug information.

      Returns:
      a boolean stating whether debug output is expected

    • setElementSplittingDebugTextReportSize

      public void setElementSplittingDebugTextReportSize(int size) throws IllegalArgumentException

      Sets a limit on the length of each debug report output by the element splitting filter.

      Parameters:
      size - the size limit for the debug output report
      Throws:
      IllegalArgumentException - if the supplied parameter is not a positive integer

    • getElementSplittingDebugTextReportSize

      public int getElementSplittingDebugTextReportSize()

      Returns the current limit on the length of each debug report output by the element splitting filter.

      Returns:
      an integer stating the current setting for the length of debug output

    • setOrphanedWordDetectionEnabled

      public void setOrphanedWordDetectionEnabled(boolean enabled)

      Sets whether or not to enable orphaned word detection and fix-up.

      Parameters:
      enabled - whether or not to enable orphaned word detection

    • isOrphanedWordDetectionEnabled

      public boolean isOrphanedWordDetectionEnabled()

      States whether or not orphaned word detection is enabled.

      Returns:
      whether or not orphaned word detection is enabled

    • setOrphanedWordLengthLimit

      public void setOrphanedWordLengthLimit(int length) throws IllegalArgumentException

      Sets the maximum number of words to consider for orphaned word detection. Sequences of words longer than the specified length will never be detected as orphaned words, regardless of the amount of changed words around them.

      Parameters:
      length - the maximum number of consecutive words that could be considered to be orphaned
      Throws:
      IllegalArgumentException - if the supplied parameter is not a positive integer

    • getOrphanedWordLengthLimit

      public int getOrphanedWordLengthLimit()

      Returns the current maximum number of words that could be considered orphaned.

      Returns:
      an int representing the number of words

    • setOrphanedWordMaxPercentage

      public void setOrphanedWordMaxPercentage(int percentage) throws IllegalArgumentException

      Sets the maximum proportion of the total change size that orphaned words can take while still being considered orphans.

      If the percentage value for a possibly orphaned section is less than or equal to this value, then it is classified as orphaned (unless there are more words than the length limit allows). The percentage value for a possibly orphaned section is calculated as follows: 

       (possibly_orphaned_words_count * 100) / (preceding_changed_words_count + possibly_orphaned_words_count + following_changed_words_count)
      Parameters:
      percentage - the maximum proportion of a changed section that orphaned words can take and still be considered orphans
      Throws:
      IllegalArgumentException - if the supplied value is not in the range 0-100

    • getOrphanedWordMaxPercentage

      public int getOrphanedWordMaxPercentage()

      Returns the maximum proportion of the total change size that orphaned words can take while still being considered orphans.

      Returns:
      an integer in the range 0-100 that represents the percentage

    • setChangeGatheringEnabled

      public void setChangeGatheringEnabled(boolean enabled)

      Sets whether to change the order of consecutive changed items to improve readability.

      If the result contains a sequence of elements whose deltaxml:deltaV2 attribute values are mixed up in a sequence of As and Bs, enabling this feature will cause them to be reordered so that they are not mixed.

      For example,

         <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>

      would be reordered to

         <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="B"/>
      Parameters:
      enabled - whether the reordering functionality should be enabled

    • isChangeGatheringEnabled

      public boolean isChangeGatheringEnabled()

      States whether or not the change reordering functionality is currently enabled.

      Returns:
      a boolean stating whether or not the functionality is enabled

    • setModifiedWhitespaceBehaviour

      public void setModifiedWhitespaceBehaviour(ModifiedWhitespaceBehaviour mode)
      Set the ModifiedWhitespaceBehaviour to use for changes to whitespace. Here, both documents must have some whitespace at a given point in order for there to be a change in whitespace. This will then be processed in accordance with the specified behaviour. Whitespace insertions and deletions are not affected by the modified whitespace behaviour.
      Parameters:
      mode - the ModifiedWhitespaceBehaviour to use for changes in whitespace

    • getModifiedWhitespaceBehaviour

      public ModifiedWhitespaceBehaviour getModifiedWhitespaceBehaviour()
      Return the current ModifiedWhitespaceBehaviour for handling changes in whitespace.
      Returns:
      a ModifiedWhitespaceBehaviour detailing how changed whitespace will be output

    • setMixedContentDetectionScope

      public void setMixedContentDetectionScope(MixedContentDetectionScope scope)
      Set the scope MixedContentDetectionScope to use for determining whether elements are of a mixed-content type. This property has no effect if DTD or XML Schema validation is enabled. The mixed-content type of an element affects whitespace handling.
      Parameters:
      scope - the MixedContentDetectionScope to use for determining if elements are mixed-content.

    • getMixedContentDetectionScope

      public MixedContentDetectionScope getMixedContentDetectionScope()
      Return the current scope MixedContentDetectionScope for determining whether elements are of a mixed-content type.
      Returns:
      the scope MixedContentDetectionScope used for determining if elements are mixed-content.

    • isCharacterByCharacterEnabled

      public boolean isCharacterByCharacterEnabled()
      Sets whether to use Character by Character in comparison.
      Returns:
      the enableCharacterByCharacter setting

    • setCharacterByCharacterEnabled

      public void setCharacterByCharacterEnabled(boolean characterByCharacter)
      Returns the setting which enables the character by character comparison.
      Parameters:
      characterByCharacter - the setting to set character by character comparison