Commit cc8f334d authored by Eli Zaretskii's avatar Eli Zaretskii

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.
parent 20ecc526
......@@ -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
......
......@@ -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
......
......@@ -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.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment