From: Phillip Lord Date: Tue, 24 Nov 2015 23:02:11 +0000 (+0000) Subject: ; Added documentation for undo-auto functionality. X-Git-Tag: emacs-25.0.90~580 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c2ba4a20aafc3ea0a907bcbb17fb41590b44cf09;p=emacs.git ; Added documentation for undo-auto functionality. * doc/lispref/text.texi: Documentation added * etc/NEWS: Annoucement added * lisp/simple.el (undo-auto--amalgamate): Docstring fix. --- diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 6d9d26f0ad1..2ceb3529689 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1343,27 +1343,38 @@ This function places a boundary element in the undo list. The undo command stops at such a boundary, and successive undo commands undo to earlier and earlier boundaries. This function returns @code{nil}. -The editor command loop automatically calls @code{undo-boundary} just -before executing each key sequence, so that each undo normally undoes -the effects of one command. As an exception, the command -@code{self-insert-command}, which produces self-inserting input -characters (@pxref{Commands for Insertion}), may remove the boundary -inserted by the command loop: a boundary is accepted for the first -such character, the next 19 consecutive self-inserting input -characters do not have boundaries, and then the 20th does; and so on -as long as the self-inserting characters continue. Hence, sequences -of consecutive character insertions can be undone as a group. - -All buffer modifications add a boundary whenever the previous undoable -change was made in some other buffer. This is to ensure that -each command makes a boundary in each buffer where it makes changes. - Calling this function explicitly is useful for splitting the effects of a command into more than one unit. For example, @code{query-replace} calls @code{undo-boundary} after each replacement, so that the user can undo individual replacements one by one. + +Mostly, however, this function is called automatically at an +appropriate time. @end defun +@defun undo-auto--amalgamate +The editor command loop automatically calls @code{undo-boundary} just +before executing each key sequence, so that each undo normally undoes +the effects of one command. A few exceptional commands are +@emph{amalgamating}: these commands generally cause small changes to +buffers. So with these a boundary is inserted only every 20th command, +so that these can be undone as a group. By default commands +@code{self-insert-command}, which produces self-inserting input +characters (@pxref{Commands for Insertion}), and @code{delete-char} +which deletes characters (@pxref{Deleting Text}) are amalgamating. +Where a command affects the contents of several buffers as may happen, +for example, if a function on the @code{post-command-hook} affects a +buffer other than the @code{current-buffer}, then @code{undo-boundary} +will be called in each of them. +@end defun + +@defvar undo-auto--boundary-timer +Some buffers, such as process buffers, can change even when no +commands are executing. In these cases, @code{undo-boundary} is +normally called periodically by the timer in this variable. Setting +this variable to non-@code{nil} prevents this behaviour. +@end defvar + @defvar undo-in-progress This variable is normally @code{nil}, but the undo commands bind it to @code{t}. This is so that various kinds of change hooks can tell when diff --git a/etc/NEWS b/etc/NEWS index 117be559192..0e38db6544d 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -262,7 +262,11 @@ at configure time. ** M-x suggests shorthands and ignores obsolete commands for completion. ** Successive single-char deletions are collapsed in the undo-log just like -successive char insertions. +successive char insertions. This behaviour can be extended to other +commands, using the `undo-auto--amalgamate' function. + +** The heuristic used to insert `undo-boundary' after each command has changed, +so that it supports commands which potentially affect multiple buffers. +++ ** New command `comment-line' bound to `C-x C-;'. diff --git a/lisp/simple.el b/lisp/simple.el index b6bf010ed3a..99e6bd31363 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -2880,7 +2880,7 @@ See also `undo-auto--buffer-undoably-changed'.") (defun undo-auto--amalgamate () "Amalgamate undo if necessary. -This function can be called after an amalgamating command. It +This function can be called before an amalgamating command. It removes the previous `undo-boundary' if a series of such calls have been made. By default `self-insert-command' and `delete-char' are the only amalgamating commands, although this