Accepting and rejecting changes

[Svante Schubert <svante.schubert@gmail.com>]

Hello,

There had been several questions and concerns about the operation lists, I called queues, I will start to answer them in this mail, doing an example of accepting and rejecting a change.

As you remember operations are representing user document changes and more important a reoccurring ODF XML change pattern, for instance "In table "/1/5" move row from "3" to "6" is a single XML element, representing just a single operation parametrized by the position of the table (integer list, aka /1/5) and two integer for start and end of the row position, e.g. <move type="row" start="/1/5/3" end="/1/5/6" /> or shorter <move t="row" s="/1/5/3" e="/1/5/6" />
By describing this XML change pattern in the spec, the CT XML is able to reference only to these changes, by using the above operation call as a label (more reasons earlier on the list).

Some might even wonder why we are discussing run-time models such as queues, when all we desire in the end is a serialization of changes in XML.
The reason is to get an idea of the required run-time design and from that to be able to design a CT XML in a way to optimize the mapping between the XML and the future run-time model (flushing).

To illuminate the bigger picture I will provide an example what happens to an operation queue, when a change is being accepted or rejected by the user.

Let us start with a simple text document with two paragraphs only.
For the ease of use let us represent a paragraph as a single character.
Let me do some ASCII art..

DOCUMENT:
a
b

All changes have been accepted.
The REVIEW OPERATION STACK is empty.

Note:
In the following accepted paragraphs will be represented by a small character, those still to be reviewed with a capital.
Comments are started by an arrow "<--"

------------------------------------------------------------
Change tracking is now enabled and a new third paragraph (with character C) will be added in between the existing two:

DOCUMENT:
a
C   <-- NEW: Add new paragraph at the 2nd position
b

REVIEW OPERATION STACK :
delete 2   <-- NEW: Inverse Operation for UNDO on review

------------------------------------------------------------
Now the users adds a paragraph at the very beginning.

DOCUMENT:
D  <-- NEW: Add new paragraph at the 1st position
a
C
b

REVIEW OPERATION STACK:
delete 1   <-- NEW: Inverse Operation for UNDO on review (always placed on top of time ordered queue)
delete 2
------------------------------------------------------------
What happens if one of the operations is being accepted or rejected?
Let us assume the user reviews the paragraph "D", what happens if this paragraph would be rejected or accepted?
As starting point in both user scenarios (accept/reject) the paragraph "D" is already part of the current ODF XML document, and its UNDO operation is in the REVIEW operation list.

As a reminder, the purpose of the undo queue is to be able to reject (and undo) earlier operations. Operations are basically ordered by time as every new user operation is simply added to the top of the stack.
The need of this queue is more evident if an information gets otherwise lost, for instance if the user would delete a paragraph with text, the undo operation would be to create it back.
Let us postulate for efficiency reasons that we only keep operations in this UNDO/REVIEW queue that still need a user review.

It should be evident that the time sorted UNDO/REVIEW queue has two ends with two very distinct semantics:
The operation on the very top is the very last operation being placed on the stack and is closest to the state of the document after change-tracking was enabled. The last tracked change.
The operation on the very bottom is the first operation being placed on the stack and is closest to the state of the document, when change-tracking at been started. The first tracked change.

In addition, let us postulate that an operation is only allowed to be deleted at one end of the queue.
Perhaps surprisingly on the first glance, an accepted change is only allowed to be deleted at the top of the queue, while the rejected change is only allowed to be deleted at the end of the queue.

Watch for yourself..


SCENARIO 1: ACCEPTING
======================
In case of the accepting the change by the user there is only one action required:
1) The inverse operation has to be taken out at the bottom of the REVIEW operation stack.

START STATE -- ACCEPTING D
----------------------------------------
DOCUMENT:
D  <-- D shall be accepted
a
C
b

REVIEW OPERATION STACK:
delete 1  <-- related to D (to be deleted, it has to be moved down to the start - closest to the already approved document state)
delete 2  <-- related to C

FINAL STATE -- ACCEPTING D
---------------------------------------
DOCUMENT:
d  <-- D has been accepted
a
C
b

REVIEW OPERATION STACK:
delete 3  <-- related to C
<-- "delete 1" related to D had been deleted

When two operations are being switched in a time ordered operation queue (where the first operation is at the bottom), the following rule have to be taken into account:
A delete (or add) component operation that is moving down the queue, but is a preceding sibling or an ancestor is resulting to a de- (or in)crease of the component position.
Think of that everything above/before an operation in the queue happens in the future, but if the operation is moved down, it suddenly influences its position.

SCENARIO 2: REJECTING D
=======================
In case of the rejecting by the user there are two actions required:
1) The "C" has to be taken out of the document by applying the UNDO operation to the document.
2) In addition the UNDO operation have to be taken out of the REVIEW operation stack.

START STATE -- REJECTING D
---------------------------------------
DOCUMENT:
D  <-- D shall be rejected
a
C
b

REVIEW OPERATION STACK:
delete 1  <-- related to D (to be delete, it has to be moved up, to be the last change added, without dependencies to the other operations)
delete 2  <-- related to C

FINAL STATE -- REJECTING D
---------------------------------------
DOCUMENT:
a
C
b

REVIEW OPERATION STACK:
delete 2  <-- related to C

Some final question and answer:  Can every operation be moved freely within the REVIEW operation stack?
No, there are limitations, which are quite evident as soon they are mentioned. For instance a deletion have to occur after the creation of a component and its manipulation have to occur within the borders of its component creation & deletion.
To ease the run-time model and improve efficiency it is thinkable to have a vertical queue for general creation of components and horizontally on each component an optional queue of the operations changing each.
The advantage would be that document changes are shown to a user in general anyway grouped by container. The only additional differentiation for the GUI might be, that changes on a component have to be sorted once more by user before being shown for review.

Please think about the above, test it (even some scenarios on your own by pen and paper) and let us discuss the experiences afterwards.

@Dennis: You asked how metadata could be aligned in the XML. A draft design was given before on the list. Missing additional metadata information can certainly be added to the XML design. I believe the problem of handcrafting the XML design is comparable easy, looking at the XML know-how gathered in this SC.

PS: Excuse the earlier delay in answers I had been traveling and excuse the future delay as I got an annoying cold and will be seldom online. Hopefully my cold did not influence too much from the above, perhaps you need to review it very closely and assume sometimes the opposite, please just read what I meant to write..  ;)

Thanks,
Svante