Changeset 0ec9f5 for doc/userguide

Timestamp:

Apr 23, 2021, 9:02:12 PM (5 years ago)

Author:

Frederik Heber <frederik.heber@…>

Branches:

Candidate_v1.7.0, stable

Children:

0fbea3

Parents:

5061d9

git-author:

Frederik Heber <frederik.heber@…> (04/06/21 20:09:39)

git-committer:

Frederik Heber <frederik.heber@…> (04/23/21 21:02:12)

Message:

Added UndoMarkAction.

NOTE: This action is necessary as not all actions are actually recorded
in the history. For example, the UndoAction is an action that is not
pushed into the history deque and also must not as further undos would
then become impossible. There are other actions that just do output
or similar things that do not change the state.
This makes it impossible to undo back to a certain state by blindly
counting actions as one cannot know from the outside whether an action
is stateless or not.

• ActionHistory allows to mark a certain HistoryElement.
• marked element is reset when undone in history.
• marked element can be set and unset via UndoMarkAction.
• ActionQueue relays undoTillMark() to ActionHistory.
• extended UndoAction by param "till-mark" to allow step-wise undo and

undoing till the set mark.

• TESTS: added regression test case on undo-mark.

File:

• doc/userguide/userguide.xml (modified) (1 diff)

doc/userguide/userguide.xml

@@ -426 +426 @@
         superfluous but it comes in very handy in the interactive ones. Also
         this should tell you that actions are placed internally in a queue, i.e. a history,
-        that undo and redo manipulate.</para>
+        that undo and redo manipulate.</para>
+        <para>Furthermore, a specific event in the history of actions can be 
+        marked using
+        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo-mark --select-all-atoms --remove-atom</programlisting>
+        Using this mark (that is unset by <programlisting>--undo-mark 0</programlisting>) 
+        one can then step directly back to that event by undoing all actions in between
+        the current and the marked event.
+        <programlisting>--undo --till-mark 1</programlisting>
+        Here, this will jump back to when the hydrogen atom was just added.
+        This function is required as not all actions produce an event in the Action 
+        history. Certain events will just calculate something and output, i.e. they
+        do not change the state. However, thereby one cannot simply count actions
+        to return back to a specific state. Hence, this function allows to mark a
+        specific state beforehand.
+        </para>
         <para>Due to a current limitation of the implementation each command can be used on the command-line only once. Note that this <emphasis role="italic">only</emphasis> applies to the command-line interface. All other interfaces, especially all interactive ones, do not have such a restriction. For the command-line interface there are several ways to work around it. Either by splitting the whole chain of commands into several chunks, each using only unique commands and using the input file (the state) to contain  and transport the intermediate stages as input for the next stage. Or to switch to other commands: often there are several possible ways of achieving a goal, especially when using selections.</para>
         <para>Being done now with the preliminaries we now go through all available actions present in MoleCuilder.</para>