[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 469b15f2 2/2: Improve documentation of exiting recursive editing
From: |
Lars Ingebrigtsen |
Subject: |
master 469b15f2 2/2: Improve documentation of exiting recursive editing |
Date: |
Mon, 20 Sep 2021 02:01:53 -0400 (EDT) |
branch: master
commit 469b15f27c6527de83979312b1a5c905e364cb8d
Author: Miha Rihtaršič <miha@kamnitnik.top>
Commit: Lars Ingebrigtsen <larsi@gnus.org>
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).
---
doc/lispref/commands.texi | 22 ++++++++++++----------
src/keyboard.c | 18 ++++++++++++++----
2 files changed, 26 insertions(+), 14 deletions(-)
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index ddd74d1..3425880 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 63bf29a..2d97429 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)