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.

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.