[Emacs-diffs] emacs-26 cc8f334: Document changes called out in NEWS

[Eli Zaretskii]

branch: emacs-26
commit cc8f334d2da736be8935f5abae51f7b1f992b343
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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 e05633a..ce62793 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1736,6 +1736,13 @@ alist
 @end example
 @end defun
 
address@hidden 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
address@hidden
address@hidden 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 8fac1c3..2951ef5 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
address@hidden Asking Multiple Y-or-N Questions
address@hidden multiple yes-or-no questions
address@hidden Asking Multiple-Choice Questions
+
+  This section describes facilities for asking the user more complex
+questions or several similar questions.
 
address@hidden 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}.
+
address@hidden read-answer question answers
address@hidden 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
address@hidden as an alist whose elements are of the following form:
+
address@hidden
+(@var{long-answer} @var{short-answer} @var{help-message})
address@hidden lisp
+
address@hidden
+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 address@hidden, 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
address@hidden is address@hidden, 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:
+
address@hidden
+(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"))))
address@hidden lisp
address@hidden defun
+
 @node Reading a Password
 @section Reading a Password
 @cindex passwords, reading
diff --git a/etc/NEWS b/etc/NEWS
index 3a949a9..578b9b8 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.