Clarify command loop's role in undo boundary (Bug#2433).

* text.texi (Undo): Clarify command loop behavior (Bug#2433).
* commands.texi (Command Overview): Mention undo-boundary call.

3 files changed, 29 insertions, 17 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 188e81178ed..b92f4aea234 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2010-06-24  Chong Yidong  <cyd@stupidchicken.com>
+
+	* text.texi (Undo): Clarify command loop behavior (Bug#2433).
+
+	* commands.texi (Command Overview): Mention undo-boundary call.
+
 2010-06-23  Glenn Morris  <rgm@gnu.org>
 
 	* abbrevs.texi, commands.texi, compile.texi, debugging.texi:
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 2111bb39de3..d22cfd955cb 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -53,16 +53,19 @@ function.  If the key is @kbd{M-x}, then it reads the name of another
 command, which it then calls.  This is done by the command
 @code{execute-extended-command} (@pxref{Interactive Call}).
 
-  To execute a command requires first reading the arguments for it.
-This is done by calling @code{command-execute} (@pxref{Interactive
-Call}).  For commands written in Lisp, the @code{interactive}
-specification says how to read the arguments.  This may use the prefix
-argument (@pxref{Prefix Command Arguments}) or may read with prompting
-in the minibuffer (@pxref{Minibuffers}).  For example, the command
-@code{find-file} has an @code{interactive} specification which says to
-read a file name using the minibuffer.  The command's function body does
-not use the minibuffer; if you call this command from Lisp code as a
-function, you must supply the file name string as an ordinary Lisp
+  Prior to executing the command, Emacs runs @code{undo-boundary} to
+create an undo boundary.  @xref{Maintaining Undo}.
+
+  To execute a command, Emacs first reads its arguments by calling
+@code{command-execute} (@pxref{Interactive Call}).  For commands
+written in Lisp, the @code{interactive} specification says how to read
+the arguments.  This may use the prefix argument (@pxref{Prefix
+Command Arguments}) or may read with prompting in the minibuffer
+(@pxref{Minibuffers}).  For example, the command @code{find-file} has
+an @code{interactive} specification which says to read a file name
+using the minibuffer.  The function body of @code{find-file} does not
+use the minibuffer, so if you call @code{find-file} as a function from
+Lisp code, you must supply the file name string as an ordinary Lisp
 function argument.
 
   If the command is a string or vector (i.e., a keyboard macro) then
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index d55b9047021..f52d1db5c9c 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1299,13 +1299,16 @@ 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 creates an undo boundary before
-each key sequence is executed.  Thus, each undo normally undoes the
-effects of one command.  Self-inserting input characters are an
-exception.  The command loop makes a boundary for the first such
-character; the next 19 consecutive self-inserting input characters do
-not make boundaries, and then the 20th does, and so on as long as
-self-inserting characters continue.
+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