[Emacs-diffs] emacs-25 e879070: Document changes in 'read-buffer' and 'read-buffer-function'

[Eli Zaretskii]

branch: emacs-25
commit e879070d8c329e4e7ccbd6687ef577589faedcf1
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Document changes in 'read-buffer' and 'read-buffer-function'
    
    * doc/lispref/minibuf.texi (High-Level Completion): Document the
    4th argument to 'read-buffer' and 'read-buffer-function'.
---
 doc/lispref/minibuf.texi |   22 ++++++++++++++--------
 etc/NEWS                 |    4 +++-
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index bf95646..ead4fe9 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1236,14 +1236,14 @@ Lisp function.  When possible, do all minibuffer input 
as part of
 reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
address@hidden read-buffer prompt &optional default require-match
address@hidden read-buffer prompt &optional default require-match predicate
 This function reads the name of a buffer and returns it as a string.
-The argument @var{default} is the default name to use, the value to
-return if the user exits with an empty minibuffer.  If address@hidden,
-it should be a string, a list of strings, or a buffer.  If it is
-a list, the default value is the first element of this list.  It is
-mentioned in the prompt, but is not inserted in the minibuffer as
-initial input.
+It prompts with @var{prompt}.  The argument @var{default} is the
+default name to use, the value to return if the user exits with an
+empty minibuffer.  If address@hidden, it should be a string, a list of
+strings, or a buffer.  If it is a list, the default value is the first
+element of this list.  It is mentioned in the prompt, but is not
+inserted in the minibuffer as initial input.
 
 The argument @var{prompt} should be a string ending with a colon and a
 space.  If @var{default} is address@hidden, the function inserts it in
@@ -1253,6 +1253,12 @@ the minibuffer with a default value (@pxref{Programming 
Tips}).
 The optional argument @var{require-match} has the same meaning as in
 @code{completing-read}.  @xref{Minibuffer Completion}.
 
+The optional argument @var{predicate}, if address@hidden, specifies a
+function to filter the buffers that should be considered: the function
+will be called with every potential candidate as its argument, and
+should return @code{nil} to reject the candidate, address@hidden to
+accept it.
+
 In the following example, the user enters @samp{minibuffer.t}, and
 then types @key{RET}.  The argument @var{require-match} is @code{t},
 and the only buffer name starting with the given input is
@@ -1287,7 +1293,7 @@ its usual work, with the same arguments passed to 
@code{read-buffer}.
 
 @defopt read-buffer-completion-ignore-case
 If this variable is address@hidden, @code{read-buffer} ignores case
-when performing completion.
+when performing completion while reading the buffer name.
 @end defopt
 
 @defun read-command prompt &optional default
diff --git a/etc/NEWS b/etc/NEWS
index 9c416ae..029e9d8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1221,7 +1221,9 @@ Use the INSIDE_EMACS environment variable instead.
 ** `save-excursion' does not save&restore the mark any more.
 Use `save-mark-and-excursion' if you want the old behavior.
 
-** read-buffer-function can now be called with a 4th argument (`predicate').
++++
+** `read-buffer' and `read-buffer-function' can now be called with a 4th
+argument (`predicate').
 
 ** completion-table-dynamic stays in the minibuffer.
 If you want the old behavior of calling the function in the buffer