From: Miha Rihtaršič Date: Mon, 20 Sep 2021 06:00:08 +0000 (+0200) Subject: Improve documentation of exiting recursive editing X-Git-Tag: emacs-28.0.90~821 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=469b15f27c6527de83979312b1a5c905e364cb8d;p=emacs.git Improve documentation of exiting recursive editing * doc/lispref/commands.texi (Recursive Editing): Mention what happens when throwing a string or any other value to 'exit. * src/keyboard.c (Frecursive_edit): Document throwing a function to 'exit (bug#49700). --- diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index ddd74d12455..3425880fec5 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -3585,17 +3585,19 @@ commands. @cindex exit recursive editing @cindex aborting To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a @code{nil} value, then -@code{recursive-edit} returns normally to the function that called it. -The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). -You can also throw a function value. In that case, +@code{recursive-edit}. This function contains the command loop; it +also contains a call to @code{catch} with tag @code{exit}, which makes +it possible to exit the recursive editing level by throwing to +@code{exit} (@pxref{Catch and Throw}). Throwing a @code{t} value +causes @code{recursive-edit} to quit, so that control returns to the +command loop one level up. This is called @dfn{aborting}, and is done +by @kbd{C-]} (@code{abort-recursive-edit}). Similarly, you can throw +a string value to make @code{recursive-edit} signal an error, printing +this string as the message. If you throw a function, @code{recursive-edit} will call it without arguments before returning. +Throwing any other value, will make @code{recursive-edit} return +normally to the function that called it. The command @kbd{C-M-c} +(@code{exit-recursive-edit}) does this. Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you diff --git a/src/keyboard.c b/src/keyboard.c index 63bf29a948c..2d97429ade2 100644 --- a/src/keyboard.c +++ b/src/keyboard.c @@ -753,10 +753,20 @@ DEFUN ("recursive-edit", Frecursive_edit, Srecursive_edit, 0, 0, "", doc: /* Invoke the editor command loop recursively. To get out of the recursive edit, a command can throw to `exit' -- for instance (throw \\='exit nil). -If you throw a value other than t, `recursive-edit' returns normally -to the function that called it. Throwing a t value causes -`recursive-edit' to quit, so that control returns to the command loop -one level up. + +The following values can be thrown to 'exit: + +- t causes `recursive-edit' to quit, so that control returns to the + command loop one level up. + +- A string causes `recursive-edit' to signal an error, printing this + string as the message. + +- A function causes `recursive-edit' to call this function without + arguments before returning normally. + +- Any other value causes `recursive-edit' to return normally to the + function that called it. This function is called by the editor initialization to begin editing. */) (void)