[Emacs-diffs] feature/documentation-for-auto-undo b283da0 1/2: ; Added documentation for undo-auto functionality.

[Noah Friedman]

branch: feature/documentation-for-auto-undo
commit b283da06102ef61cc12f3d4599dd6b5f663f1ffd
Author: Phillip Lord <address@hidden>
Commit: Phillip Lord <address@hidden>

    ; Added documentation for undo-auto functionality.
    
     * doc/lispref/text.texi: Documentation added
     * etc/NEWS: Annoucement added
     * lisp/simple.el (undo-auto--amalgamate): Docstring fix.
---
 doc/lispref/text.texi | 41 ++++++++++++++++++++++++++---------------
 etc/NEWS              |  6 +++++-
 lisp/simple.el        |  2 +-
 3 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6d9d26f..2ceb352 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
address@hidden, 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
 
address@hidden 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
address@hidden: 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
address@hidden, 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.
address@hidden defun
+
address@hidden 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 address@hidden prevents this behaviour.
address@hidden 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 46910b0..b18fc61 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -289,7 +289,11 @@ few or no entries have changed.
 * Editing Changes in Emacs 25.1
 
 ** 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.
 
 ** Unicode names entered via C-x 8 RET now use substring completion by default.
 
diff --git a/lisp/simple.el b/lisp/simple.el
index deb5c88..c54afc8 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2888,7 +2888,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