(Basic Completion): Note that read-file-name-completion-ignore-case

and read-buffer-completion-ignore-case can override
completion-ignore-case.
(Minibuffer Completion): Document completing-read changes.
(Completion Commands): Avoid mentioning partial completion mode.
Document minibuffer-completion-confirm changes, and
minibuffer-confirm-exit-commands.
(High-Level Completion): Document new require-match behavior for
read-buffer.  Document read-buffer-completion-ignore-case.
(Reading File Names): Document new require-match behavior for
read-file-name.

1 files changed, 73 insertions, 46 deletions

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index a03e8036a93..cb600990f57 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -824,7 +824,11 @@ it returns, @code{test-completion} returns in turn.
 
 @defvar completion-ignore-case
 If the value of this variable is non-@code{nil}, Emacs does not
-consider case significant in completion.
+consider case significant in completion.  Note, however, that this
+variable is overridden by @code{read-file-name-completion-ignore-case}
+within @code{read-file-name} (@pxref{Reading File Names}), and by
+@code{read-buffer-completion-ignore-case} within @code{read-buffer}
+(@pxref{High-Level Completion}).
 @end defvar
 
 @defvar completion-regexp-list
@@ -871,15 +875,33 @@ Some of these commands also call @code{test-completion}.  Thus, if
 @var{collection} and @code{completion-ignore-case}.  @xref{Definition
 of test-completion}.
 
-If @var{require-match} is @code{nil}, the exit commands work regardless
-of the input in the minibuffer.  If @var{require-match} is @code{t}, the
-usual minibuffer exit commands won't exit unless the input completes to
-an element of @var{collection}.  If @var{require-match} is
-@code{confirm-only}, the user can exit with any input, but she will
-be asked for a confirmation if the input is not an element of
-@var{collection}.  Any other value of @var{require-match} behaves like
-@code{t}, except that the exit commands won't exit if it does non-null
-completion.
+The value of the optional argument @var{require-match} determines how
+the user may exit the minibuffer:
+
+@itemize @bullet
+@item
+If @code{nil}, the usual minibuffer exit commands work regardless of
+the input in the minibuffer.
+
+@item
+If @code{t}, the usual minibuffer exit commands won't exit unless the
+input completes to an element of @var{collection}.
+
+@item
+If @code{confirm}, the user can exit with any input, but is asked for
+confirmation if the input is not an element of @var{collection}.
+
+@item
+If @code{confirm-after-completion}, the user can exit with any input,
+but is asked for confirmation if the preceding command was a
+completion command (i.e., one of the commands in
+@code{minibuffer-confirm-exit-commands}) and the resulting input is
+not an element of @var{collection}.  @xref{Completion Commands}.
+
+@item
+Any other value of @var{require-match} behaves like @code{t}, except
+that the exit commands won't exit if it performs completion.
+@end itemize
 
 However, empty input is always permitted, regardless of the value of
 @var{require-match}; in that case, @code{completing-read} returns the
@@ -948,12 +970,7 @@ They are described in the following section.
 @subsection Minibuffer Commands that Do Completion
 
   This section describes the keymaps, commands and user options used
-in the minibuffer to do completion.  The description refers to the
-situation when Partial Completion mode is disabled (as it is by
-default).  When enabled, this minor mode uses its own alternatives to
-some of the commands described below.  @xref{Completion Options,,,
-emacs, The GNU Emacs Manual}, for a short description of Partial
-Completion mode.
+in the minibuffer to do completion.
 
 @defvar minibuffer-completion-table
 The value of this variable is the collection used for completion in
@@ -969,10 +986,25 @@ minibuffer completion functions.
 @end defvar
 
 @defvar minibuffer-completion-confirm
-When the value of this variable is non-@code{nil}, Emacs asks for
-confirmation of a completion before exiting the minibuffer.
-@code{completing-read} binds this variable, and the function
-@code{minibuffer-complete-and-exit} checks the value before exiting.
+This variable determines whether Emacs asks for confirmation before
+exiting the minibuffer; @code{completing-read} binds this variable,
+and the function @code{minibuffer-complete-and-exit} checks the value
+before exiting.  If the value is @code{nil}, confirmation is not
+required.  If the value is @code{confirm}, the user may exit with an
+input that is not a valid completion alternative, but Emacs asks for
+confirmation.  If the value is @code{confirm-after-completion}, the
+user may exit with an input that is not a valid completion
+alternative, but Emacs asks for confirmation if the user submitted the
+input right after any of the completion commands in
+@code{minibuffer-confirm-exit-commands}.
+@end defvar
+
+@defvar minibuffer-confirm-exit-commands
+This variable holds a list of commands that cause Emacs to ask for
+confirmation before exiting the minibuffer, if the @var{require-match}
+argument to @code{completing-read} is @code{confirm-after-completion}.
+The confirmation is requested if the user attempts to exit the
+minibuffer immediately after calling any command in this list.
 @end defvar
 
 @deffn Command minibuffer-complete-word
@@ -1113,7 +1145,7 @@ 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}.
 
-@defun read-buffer prompt &optional default existing
+@defun read-buffer prompt &optional default require-match
 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 non-@code{nil},
@@ -1127,17 +1159,12 @@ space.  If @var{default} is non-@code{nil}, the function inserts it in
 @var{prompt} before the colon to follow the convention for reading from
 the minibuffer with a default value (@pxref{Programming Tips}).
 
-If @var{existing} is non-@code{nil}, then the name specified must be
-that of an existing buffer.  The usual commands to exit the minibuffer
-do not exit if the text is not valid, and @key{RET} does completion to
-attempt to find a valid name.  If @var{existing} is neither @code{nil}
-nor @code{t}, confirmation is required after completion.  (However,
-@var{default} is not checked for validity; it is returned, whatever it
-is, if the user exits with the minibuffer empty.)
+The optional argument @var{require-match} has the same meaning as in
+@code{completing-read}.  @xref{Minibuffer Completion}.
 
 In the following example, the user enters @samp{minibuffer.t}, and
-then types @key{RET}.  The argument @var{existing} is @code{t}, and the
-only buffer name starting with the given input is
+then types @key{RET}.  The argument @var{require-match} is @code{t},
+and the only buffer name starting with the given input is
 @samp{minibuffer.texi}, so that name is the value.
 
 @example
@@ -1168,6 +1195,11 @@ that call @code{read-buffer} to read a buffer name will actually use the
 @code{iswitchb} package to read it.
 @end defvar
 
+@defvar read-buffer-completion-ignore-case
+If this variable is non-@code{nil}, @code{read-buffer} ignores case
+when performing completion.
+@end defvar
+
 @defun read-command prompt &optional default
 This function reads the name of a command and returns it as a Lisp
 symbol.  The argument @var{prompt} is used as in
@@ -1302,23 +1334,18 @@ and @code{read-input-method-name}, in @ref{Input Methods}.
 for reading file names and shell commands.  They provide special
 features including automatic insertion of the default directory.
 
-@defun read-file-name prompt &optional directory default existing initial predicate
+@defun read-file-name prompt &optional directory default require-match initial predicate
 This function reads a file name in the minibuffer, prompting with
 @var{prompt} and providing completion.
 
-If @var{existing} is non-@code{nil}, then the user must specify the name
-of an existing file; @key{RET} performs completion to make the name
-valid if possible, and then refuses to exit if it is not valid.  If the
-value of @var{existing} is neither @code{nil} nor @code{t}, then
-@key{RET} also requires confirmation after completion.  If
-@var{existing} is @code{nil}, then the name of a nonexistent file is
-acceptable.
+The optional argument @var{require-match} has the same meaning as in
+@code{completing-read}.  @xref{Minibuffer Completion}.
 
 @code{read-file-name} uses
 @code{minibuffer-local-filename-completion-map} as the keymap if
-@var{existing} is @code{nil}, and uses
-@code{minibuffer-local-filename-must-match-map} if @var{existing} is
-non-@code{nil}.  @xref{Completion Commands}.
+@var{require-match} is @code{nil}, and uses
+@code{minibuffer-local-filename-must-match-map} if @var{require-match}
+is non-@code{nil}.  @xref{Completion Commands}.
 
 The argument @var{directory} specifies the directory to use for
 completion of relative file names.  It should be an absolute directory
@@ -1341,7 +1368,7 @@ contents that @code{read-file-name} inserted initially.  The initial
 minibuffer contents are always non-empty if
 @code{insert-default-directory} is non-@code{nil}, as it is by
 default.  @var{default} is not checked for validity, regardless of the
-value of @var{existing}.  However, if @var{existing} is
+value of @var{require-match}.  However, if @var{require-match} is
 non-@code{nil}, the initial minibuffer contents should be a valid file
 (or directory) name.  Otherwise @code{read-file-name} attempts
 completion if the user exits without any editing, and does not return
@@ -1361,9 +1388,9 @@ types @key{RET} without any editing, @code{read-file-name} simply
 returns the pre-inserted contents of the minibuffer.
 
 If the user types @key{RET} in an empty minibuffer, this function
-returns an empty string, regardless of the value of @var{existing}.
-This is, for instance, how the user can make the current buffer visit
-no file using @code{M-x set-visited-file-name}.
+returns an empty string, regardless of the value of
+@var{require-match}.  This is, for instance, how the user can make the
+current buffer visit no file using @code{M-x set-visited-file-name}.
 
 If @var{predicate} is non-@code{nil}, it specifies a function of one
 argument that decides which file names are acceptable completion
@@ -1420,7 +1447,7 @@ If this variable is non-@code{nil}, @code{read-file-name} ignores case
 when performing completion.
 @end defvar
 
-@defun read-directory-name prompt &optional directory default existing initial
+@defun read-directory-name prompt &optional directory default require-match initial
 This function is like @code{read-file-name} but allows only directory
 names as completion possibilities.