Commit c2ba4a20 authored by Phillip Lord's avatar Phillip Lord

; Added documentation for undo-auto functionality.

 * doc/lispref/text.texi: Documentation added
 * etc/NEWS: Annoucement added
 * lisp/simple.el (undo-auto--amalgamate): Docstring fix.
parent 3eb93c07
......@@ -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
......
......@@ -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-;'.
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment