Requirements

Note

This page is based on the initial meeting at W3C TPAC in Lyon, Plenary day on 31st October 2012. There are some additions also from discussions and presentation at DITA Europe in November 2012 where this issue was discussed - the DITA community wants any standard to work for DITA.

This is not intended as a definitive statement of requirements, rather it is a strawman to begin the discussion - a suggested starting point but are based on work over the past couple of years in this area. There is a strawman proposal also, which we will post for discussion.

Summary

The purpose of this community group is to work towards a standard for change tracking markup (referred to as CHANGEML below). 'Change tracking markup' means XML markup that records changes to an XML document.

CHANGEML will potentially be useful for many communities:

- for developers of XML schemas because they will be able to access the standard to add change tracking to their own schema

- for developers of XML tools because they will be able to process changes in a standard way

- for developers of XML authoring/editing tools because they will be able to track changes in a standard way

- for users of XML because there will be better support for handling change, both in the schemas they may be using and the tools to process their data.

What are the use cases?

- to support change tracking (including accept/reject changes) within an XML editor or other application

- to roll-back changes so that a document can be rolled-back to a previous version

- to view changes

- to support audit trails

Scope

Scope: The tracking of any change to the content of the root node of any XML document.

Rationale: this is the content that is processed by an XML processor, and it is unlikely that such a processor would know what to do with changes outside the scope.

Notes

Changes to entity references would need to be tracked, i.e. entity references would need to be preserved.

Rationale: these are part of the structure of the document and are typically only expanded during a final stage of processing. Certainly a human editor would expect these to be preserved.

Changes to comments would need to be tracked.

Rationale: comments can be an important part of a document, so it would certainly be good to be able to track changes even if only at a basic level, e.g. by replacing a comment with a new version of the comment.

Would changes to Processing Instructions need to be tracked?

Exclusions: The standard would NOT cover changes to DTDs, XML doctype declarations, doctype declaration (including internal subset, entity declarations).

Rationale: it would be very difficult to work out how to represent changes in these areas using XML markup, and as mentioned above it is doubtful whether an XML processor would be able to do anything meaningful with such information.

Requirements

1. It should be 'easy' to ignore the tracked changes and get the latest version of a document

Rationale: not all tools will be able to handle changes, and so they should easily be able to access the latest version, e.g. by simply ignoring elements/attributes in one or more namespaces.

2. All changes should be represented in standard XML markup

Rationale: so the changes can be processed using standard XML tools.

3. The standard should include a way to convert all changes from markup to Processing Instructions (PIs) and vice versa in a lossless way.

Rationale: most XML editors use PIs now for change tracking because it makes validation of the document easier, and this may be a convenient representation for other tools also. A standard with a well-defined PI representation would therefore be easier for XML editors to adopt using current technology.

4. It should be possible to represent the change between any two states/versions of a document as a 'single' change.

Rationale: it is clear that a 'single' change may involve changes to more than one element/attribute/PCDATA item in a document. Any change tracking standard should therefore be able to cope with this.

5. The reversal/rejection of a change should always yield a document that is well-formed XML.

Rationale: it would seem odd if an XML standard allowed for results that did not conform to the XML standard itself.

6. The standard should include a definition of how to reverse/reject a change.

Rationale: this would mean that standard software could be used to accept or reject changes without deep knowledge about the semantics of the XML.

7. The standard should include a definition of how to represent dependency of changes, e.g. to prevent accepting/rejecting a change that would result in a document that is not well-formed or is by some other measure 'invalid'.

Rationale: any history of changes to a document will have dependencies, and the change tracking standard must be able to represent these in some way.