[climacs-cvs] CVS climacs/Doc

[thenriksen]

Update of /project/climacs/cvsroot/climacs/Doc
In directory clnet:/tmp/cvs-serv26713/Doc

Modified Files:
	climacs-internals.texi 
Log Message:
Updated the undo protocol documentation (and added missing reader to
the implementation).


--- /project/climacs/cvsroot/climacs/Doc/climacs-internals.texi	2006/07/27 10:39:32	1.21
+++ /project/climacs/cvsroot/climacs/Doc/climacs-internals.texi	2006/07/27 13:58:57	1.22
@@ -1771,7 +1771,7 @@
 The base class for all undo trees. 
 @end deftp
 
- at deftp {protocol class} undo-record
+ at deftp {protocol class} standard-undo-record
 
 The base class for all undo records.
 
@@ -1851,36 +1851,37 @@
 
 @section How the buffer handles undo
 
- at deftp {class} undoable-buffer
+ at deftp {class} undo-mixin
 
-This is a subclass of standard-buffer.  Instantiating this class
-creates an empy undo-tree for the buffer.
+This is a mixin class that buffer classes can inherit from. It contains
+an undo tree, an undo accumulator and a flag specifyng whether or not it
+is currently performing undo. The undo tree and undo accumulators are
+initially empty.
 @end deftp
 
- at deffn {generic function} undo-tree undoable-buffer
+ at deffn {generic function} undo-tree undo-mixin
 
-Return the undo-tree of the buffer. 
+A slot reader.  Returns the undo-tree of the buffer.
 @end deffn
 
-Undo is implemented as :after methods on, insert-buffer-object,
+Undo is implemented as :before methods on, insert-buffer-object,
 insert-buffer-sequence and delete-buffer-range specialized on
-undoable-buffer.
+undo-mixin.
 
- at deftp {special variable} *undo-accumulate*
-
-This variable is initially nil (the empty list).  The :after methods
-on insert-buffer-object, insert-buffer-sequence, and
-delete-buffer-range push undo records on to this list.
- at end deftp
+ at deffn {generic-function} undo-accumulate undo-mixin
+A slot accessor.  This list returned by thus function is initially nil
+(the empty list).  The :before methods on insert-buffer-object,
+insert-buffer-sequence, and delete-buffer-range push undo records on to
+this list.
+ at end deffn
 
- at deftp {special variable} *performing-undo*
+ at deffn {generic-function} performing-undo undo-mixin
 
-This variable is initially nil.  The :after methods on
+A slot accessor.  This slot is initially nil.  The :before methods on
 insert-buffer-object, insert-buffer-sequence, and delete-buffer-range
-push undo records onto *undo-accumulate* only if *performing-undo* is
-nil so that no undo information is added as a result of an undo
-operation.
- at end deftp
+push undo records onto the undo accumulator only if this slot is nil so
+that no undo information is added as a result of an undo operation.
+ at end deffn
 
 Three subclasses `insert-record', `delete-record', and
 `compound-record' of undo-record are used.  An insert record stores a
@@ -1888,20 +1889,21 @@
 stores a position and the length of the sequence to be deleted, and a
 compound record stores a list of other undo records.
 
-The :after methods on insert-buffer-object and insert-buffer-sequence
-push a record of type delete-record onto *undo-accumulate*, and the
-:after method on delete-buffer-range pushes a record of type
-insert-record onto *undo-accumulate*.
-
- at deffn {macro} with-undo buffer &body body
-
-This macro first binds *undo-accumulate* to nil.  Then it executes
-the forms of body.  Finally, it calls add-undo with an undo record
-and the undo tree of the buffer.  If *undo-accumulate* contains a
-single undo record, it is passed as is to add-undo.  If it contains
-several undo records, a compound undo record is constructed out of
-the list and passed to add-undo.  Finally, if *undo-accumulate* is
-nil, add-undo is not called at all.
+The :before methods on insert-buffer-object and insert-buffer-sequence
+push a record of type delete-record onto the undo accumulator for the
+buffer, and the :before method on delete-buffer-range pushes a record of
+type insert-record onto the undo accumulator.
+
+ at deffn {macro} with-undo (get-buffers-exp) &body body
+
+This macro executes the forms of `body', registering changes made to the
+list of buffers retrieved by evaluating `get-buffers-exp'. When `body'
+has run, for each buffer it will call add-undo with an undo record and
+the undo tree of the buffer.  If the changes done by `body' to the
+buffer has resulted in only a single undo record, it is passed as is to
+add-undo.  If it contains several undo records, a compound undo record
+is constructed out of the list and passed to add-undo.  Finally, if the
+buffer has no undo records, add-undo is not called at all.
 @end deffn
 
 To avoid storing an undo record for each object that is inserted,
@@ -1909,24 +1911,24 @@
 the sequence in the last delete-record.
 
 The method on flip-undo-record specialized on insert-record binds
-*performing-undo* to t, inserts the sequence of objects in the
-buffer, and calls change-class to convert the insert-record to a
+performing-undo for the buffer to t, inserts the sequence of objects in
+the buffer, and calls change-class to convert the insert-record to a
 delete-record, giving it a the length of the stored sequence.
 
 The method on flip-undo-record specialized on delete-record binds
-*performing-undo* to t, deletes the range from the buffer, and calls
-change-class to convert the delete-record to an insert-record, giving
-it the sequence at the stored offset in the buffer with the specified
-length.
+performing-undo for the buffer to t, deletes the range from the buffer,
+and calls change-class to convert the delete-record to an insert-record,
+giving it the sequence at the stored offset in the buffer with the
+specified length.
 
 The method on flip-undo-record specialized on compound-record binds
-*performing-undo* to t, recursively calls flip-undo-record on each
-element of the list of undo records, and finally destructively
+performing-undo for the buffer to t, recursively calls flip-undo-record
+on each element of the list of undo records, and finally destructively
 reverses the list.
 
- at deftp {class} buffer-undo-record
+ at deftp {class} climacs-undo-record
 
-A subclass of undo-record.
+A subclass of standard-undo-record.
 @end deftp
 
 @deftp {initarg} :buffer
@@ -1934,6 +1936,11 @@
 The buffer to which the record belongs. 
 @end deftp
 
+ at deftp {class} simple-undo-record
+
+A subclass of climacs-undo-record.
+ at end deftp
+
 @deftp {initarg} :offset
 
 This initarg is mandatory and supplies the offset that determines the
@@ -1960,7 +1967,7 @@
 
 @deftp {class} insert-record
 
-A subclass of buffer-undo-record.  Whenever objects are deleted, the
+A subclass of simple-undo-record.  Whenever objects are deleted, the
 sequence of objectgs is stored in an insert record containing a mark.
 @end deftp
 
@@ -1972,11 +1979,13 @@
 
 @deftp {class} compound-record
 
-A subclass of buffer-undo-record.  This record simply contains a list
+A subclass of simple-undo-record.  This record simply contains a list
 of other records.
 @end deftp
 
 @deftp {initarg} :records
+
+A list of output records.
 @end deftp
 
 @chapter Kill Ring Protocol