From: Eli Zaretskii Date: Tue, 28 Mar 2023 18:08:12 +0000 (+0300) Subject: Improve documentation of 'read-choice' and related symbols X-Git-Tag: emacs-29.0.90~69 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c1eac5b6586a79e0d84cbdb2ea310b7acee66414;p=emacs.git Improve documentation of 'read-choice' and related symbols * doc/lispref/commands.texi (Reading One Event): * lisp/subr.el (read-char-choice-use-read-key, read-char-choice) (read-char-choice-with-read-key, y-or-n-p-use-read-key): Improve documentation of these functions and variables. --- diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 20be706bebd..62a0939a47e 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -3215,15 +3215,24 @@ unspecified, the only fallback disabled is downcasing of the last event. @end defun +@vindex read-char-choice-use-read-key @defun read-char-choice prompt chars &optional inhibit-quit -This function uses @code{read-key} to read and return a single -character. It ignores any input that is not a member of @var{chars}, -a list of accepted characters. Optionally, it will also ignore -keyboard-quit events while it is waiting for valid input. If you bind -@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value -while calling @code{read-char-choice}, then pressing @code{help-char} -causes it to evaluate @code{help-form} and display the result. It -then continues to wait for a valid input character, or keyboard-quit. +This function uses @code{read-from-minibuffer} to read and return a +single character that is a member of @var{chars}, which should be a +list of single characters. It discards any input characters that are +not members of @var{chars}, and shows a message to that effect. + +The optional argument @var{inhibit-quit} is by default ignored, but if +the variable @code{read-char-choice-use-read-key} is non-@code{nil}, +this function uses @code{read-key} instead of +@code{read-from-minibuffer}, and in that case @var{inhibit-quit} +non-@code{nil} means ignore keyboard-quit events while waiting for +valid input. In addition, if @code{read-char-choice-use-read-key} is +non-@code{nil}, binding @code{help-form} (@pxref{Help Functions}) to a +non-@code{nil} value while calling this function causes it to evaluate +@code{help-form} and display the result when the user presses +@code{help-char}; it then continues to wait for a valid input +character, or for keyboard-quit. @end defun @defun read-multiple-choice prompt choices &optional help-string show-help long-form diff --git a/lisp/subr.el b/lisp/subr.el index 8d27c831c96..a9d93e5fe5e 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -3196,34 +3196,38 @@ This function is used by the `interactive' code letter \"n\"." n)) (defvar read-char-choice-use-read-key nil - "Prefer `read-key' when reading a character by `read-char-choice'. -Otherwise, use the minibuffer. + "If non-nil, use `read-key' when reading a character by `read-char-choice'. +Otherwise, use the minibuffer (this is the default). -When using the minibuffer, the user is less constrained, and can -use the normal commands available in the minibuffer, and can, for -instance, switch to another buffer, do things there, and then -switch back again to the minibuffer before entering the -character. This is not possible when using `read-key', but using -`read-key' may be less confusing to some users.") +When reading via the minibuffer, you can use the normal commands +available in the minibuffer, and can, for instance, temporarily +switch to another buffer, do things there, and then switch back +to the minibuffer before entering the character. This is not +possible when using `read-key', but using `read-key' may be less +confusing to some users.") (defun read-char-choice (prompt chars &optional inhibit-keyboard-quit) - "Read and return one of CHARS, prompting for PROMPT. -Any input that is not one of CHARS is ignored. - -By default, the minibuffer is used to read the key -non-modally (see `read-char-from-minibuffer'). If -`read-char-choice-use-read-key' is non-nil, the modal `read-key' -function is used instead (see `read-char-choice-with-read-key')." + "Read and return one of the characters in CHARS, prompting with PROMPT. +CHARS should be a list of single characters. +The function discards any input character that is not one of CHARS, +and shows a message to the effect that it is not one of the expected +charcaters. + +By default, use the minibuffer to read the key non-modally (see +`read-char-from-minibuffer'). But if `read-char-choice-use-read-key' +is non-nil, the modal `read-key' function is used instead (see +`read-char-choice-with-read-key')." (if (not read-char-choice-use-read-key) (read-char-from-minibuffer prompt chars) (read-char-choice-with-read-key prompt chars inhibit-keyboard-quit))) (defun read-char-choice-with-read-key (prompt chars &optional inhibit-keyboard-quit) - "Read and return one of CHARS, prompting for PROMPT. + "Read and return one of the characters in CHARS, prompting with PROMPT. +CHARS should be a list of single characters. Any input that is not one of CHARS is ignored. If optional argument INHIBIT-KEYBOARD-QUIT is non-nil, ignore -`keyboard-quit' events while waiting for a valid input. +`keyboard-quit' events while waiting for valid input. If you bind the variable `help-form' to a non-nil value while calling this function, then pressing `help-char' @@ -3519,15 +3523,15 @@ Also discard all previous input in the minibuffer." (sit-for 2))) (defvar y-or-n-p-use-read-key nil - "Prefer `read-key' when answering a \"y or n\" question by `y-or-n-p'. -Otherwise, use the minibuffer. - -When using the minibuffer, the user is less constrained, and can -use the normal commands available in the minibuffer, and can, for -instance, switch to another buffer, do things there, and then -switch back again to the minibuffer before entering the -character. This is not possible when using `read-key', but using -`read-key' may be less confusing to some users.") + "Use `read-key' when reading answers to \"y or n\" questions by `y-or-n-p'. +Otherwise, use the `read-from-minibuffer' to read the answers. + +When reading via the minibuffer, you can use the normal commands +available in the minibuffer, and can, for instance, temporarily +switch to another buffer, do things there, and then switch back +to the minibuffer before entering the character. This is not +possible when using `read-key', but using `read-key' may be less +confusing to some users.") (defvar from--tty-menu-p nil "Non-nil means the current command was invoked from a TTY menu.")