Configuring PutDocDiffing in AppData

In the PutDoc adapter, the standard functionality relies on the modified flag being set to yes in the xy_object Processing Instruction (PI) to decide if the Object Mapped Element (OME) should be written back to Contenta.

XML example of OME:
Example: XML example of OME
<FM><?xy_object id="xyent-rw002" name="" objecttype="" modified="no" access="write"?>
<P>Placed in public domain, 2006.</P>
<P>This version by Willy Carpenter, 1952-1973.</P>
</FM>
In some instances, because of issues with editor-specific custom code that is responsible for setting the modified flag equal to yes when an edit is made, the PutDoc adapter needs to do a second check for document modification. The PutDoc adapter attempts to detect missed changes by doing a compare of original with potentially modified OMEs as the concatenated document file is busted into its constituent OMEs. The comparison is capable of detecting the following changes in document data where the OME’s xy_object PI contains the settings modified=”no” access=”write”:
  • content changes, including changes to element attributes
  • child OME deletes and moves (into and out of the parent)
  • child OME reorders
  • new child OME, where the editor custom code adds a xy_object PI to the newly inserted OME but fails to update the parent OME’s PI to modified="yes"
Diffing of XML and SGML can be precarious because there are a variety of “insignificant” formatting changes automatically generated by the various editors when they save the data back to the document file. These differences should be considered “false positives”. A few examples of the insignificant differences include:
  • new line between element tags
  • space to new line character convention or vice versa
  • redundant newlines
  • redundant spaces
  • change in the order of element attributes (Epic likes to save attributes in alphabetical order, Frame in DTD declaration order, and XMetaL doesn’t sort them. Dynamic Import (DI) sorts attributes in DTD declaration order before importing.)

The callback pcm_normalize in the custom bust module, CustomBustDefault.pm, of the PutDoc adapter attempts to illuminate these “false positives” during the comparison process. None of these differences are actually filtered from the document data that is written back to the object should a difference be found. The reason that the code is exposed in a callback is that there will probably be additional “false positives” that need to be ignored in some instances and the callback may be ignoring differences that you may deem significant.

By default PutDocDiffing is off. To turn it on you need to make the proper settings in AppData. There are seven (7) possible levels which can apply to all users (Global) and/or they can be user specific.

The user-specific setting is used first, if there is no setting for the user then the Global setting is used. The levels are:

LevelDescription
0off
1on - silent mode
2on - the editor tool displays a message if differences found.

The checkout directory is not deleted and a log file is generated in the checkout directory describing the differences found by the diff'ing process.

*Not permitted with Contenta Web editor tools.

3on - same as level 2 except no modifications are imported and no objects are unlocked if differences are found by the PutDocDiffing process.

*Not permitted with Contenta Web editor tools.

11on - same as level 1 except changes in attribute order are not ignored.
12on - same as level 2 except that changes in attribute order are not ignored.

*Not permitted with Contenta Web editor tools.

13on - same as level 3 except that changes in attribute order are not ignored.

*Not permitted with Contenta Web editor tools.

*With the Contenta Web editor tools for Epic, Frame and XMetaL only levels 0, 1 and 11 are permitted.

The check out directory on the web server is Contenta_home/web/cw_common when PutDocDiffing is turned on instead of Contenta_home/temp. The check-out directory is not deleted until the user has successfully checked-in the document.

Levels 1, 2 and 3, which ignore attribute order changes, only work with well-formed data, meaning that PutDocDiffing fails with a parsing error if the data type is SGML, in some cases for these 3 settings. With ArborText, attribute sorting can be turned off if the data type is SGML. (See your editor documentation for details).