From cc8f334d2da736be8935f5abae51f7b1f992b343 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 15 Sep 2018 11:51:34 +0300 Subject: [PATCH] Document changes called out in NEWS * doc/lispref/lists.texi (Association Lists): Document 'assoc-delete-all'. * doc/lispref/minibuf.texi (Minibuffers): Adapt menu. (Multiple Queries): Document 'read-answer'. * etc/NEWS: Reflect the above documentation in the respective entries. --- doc/lispref/lists.texi | 7 +++++ doc/lispref/minibuf.texi | 55 +++++++++++++++++++++++++++++++++++++--- etc/NEWS | 3 +++ 3 files changed, 62 insertions(+), 3 deletions(-) diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index e05633a881d..ce62793550d 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1736,6 +1736,13 @@ alist @end example @end defun +@defun assoc-delete-all key alist +This function deletes from @var{alist} all the elements whose @sc{car} +is @code{equal} to @var{key}. It works like @code{assq-delete-all}, +except for the predicate used for comparing alist elements with +@var{key}. +@end defun + @defun rassq-delete-all value alist This function deletes from @var{alist} all the elements whose @sc{cdr} is @code{eq} to @var{value}. It returns the shortened alist, and diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 8fac1c3e762..2951ef5aaec 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -26,7 +26,7 @@ argument. * Initial Input:: Specifying initial contents for the minibuffer. * Completion:: How to invoke and customize completion. * Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. +* Multiple Queries:: Asking complex questions. * Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. * Minibuffer Windows:: Operating on the special minibuffer windows. @@ -2084,9 +2084,12 @@ Do you really want to remove everything? (yes or no) @end defun @node Multiple Queries -@section Asking Multiple Y-or-N Questions -@cindex multiple yes-or-no questions +@section Asking Multiple-Choice Questions + + This section describes facilities for asking the user more complex +questions or several similar questions. +@cindex multiple yes-or-no questions When you have a series of similar questions to ask, such as ``Do you want to save this buffer?'' for each buffer in turn, you should use @code{map-y-or-n-p} to ask the collection of questions, rather than @@ -2180,6 +2183,52 @@ The return value of @code{map-y-or-n-p} is the number of objects acted on. @c FIXME An example of this would be more useful than all the @c preceding examples of simple things. +If you need to ask the user a question that might have more than just +2 answers, use @code{read-answer}. + +@defun read-answer question answers +@vindex read-answer-short +This function prompts the user with text in @var{question}, which +should end in the @samp{SPC} character. The function includes in the +prompt the possible responses in @var{answers} by appending them to +the end of @var{question}. The possible responses are provided in +@var{answers} as an alist whose elements are of the following form: + +@lisp +(@var{long-answer} @var{short-answer} @var{help-message}) +@end lisp + +@noindent +where @var{long-answer} is the complete text of the user response, a +string; @var{short-answer} is a short form of the same response, a +single character; and @var{help-message} is the text that describes +the meaning of the answer. If the variable @code{read-answer-short} +is non-@code{nil}, the prompt will show the short variants of the +possible answers and the user is expected to type the single +characters shown in the prompt; otherwise the prompt will show the +long variants of the answers, and the user is expected to type the +full text of one of the answers and end by pressing @key{RET}. If +@code{use-dialog-box} is non-@code{nil}, and this function was invoked +by mouse events, the question and the answers will be displayed in a +GUI dialog box. + +The function returns the text of the @var{long-answer} selected by the +user, regardless of whether long or short answers were shown in the +prompt and typed by the user. + +Here is an example of using this function: + +@lisp +(let ((read-answer-short t)) + (read-answer "Foo " + '(("yes" ?y "perform the action") + ("no" ?n "skip to the next") + ("all" ?! "perform for the rest without more questions") + ("help" ?h "show help") + ("quit" ?q "exit")))) +@end lisp +@end defun + @node Reading a Password @section Reading a Password @cindex passwords, reading diff --git a/etc/NEWS b/etc/NEWS index 3a949a9805c..578b9b8d956 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -78,6 +78,7 @@ in its NEWS.) ** VC +--- *** VC support for Mercurial was improved. Emacs now avoids invoking 'hg' as much as possible, for faster operation. (This and the following changes were actually made in Emacs 26.1, but @@ -125,9 +126,11 @@ obsolete it. * Lisp Changes in Emacs 26.2 ++++ ** The new function 'read-answer' accepts either long or short answers depending on the new customizable variable 'read-answer-short'. ++++ ** New function 'assoc-delete-all'. Like 'assq-delete-all', but uses 'equal' for comparison. -- 2.39.2