From 51422d6dde17e1a655ec0161b537655b09cd630c Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Thu, 24 Jun 2010 15:05:47 -0400 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 6 ++++++ doc/lispref/commands.texi | 23 +++++++++++++---------- doc/lispref/text.texi | 17 ++++++++++------- 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 + + * text.texi (Undo): Clarify command loop behavior (Bug#2433). + + * commands.texi (Command Overview): Mention undo-boundary call. + 2010-06-23 Glenn Morris * 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 -- 2.39.2