[Emacs-diffs] emacs/doc/lispref minibuf.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/03/17 04:54:14

Modified files:
        doc/lispref    : minibuf.texi 

Log message:
        (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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/minibuf.texi?cvsroot=emacs&r1=1.17&r2=1.18

Patches:
Index: minibuf.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/minibuf.texi,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -b -r1.17 -r1.18
--- minibuf.texi        9 Jan 2009 05:22:05 -0000       1.17
+++ minibuf.texi        17 Mar 2009 04:54:14 -0000      1.18
@@ -824,7 +824,11 @@
 
 @defvar completion-ignore-case
 If the value of this variable is address@hidden, 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
address@hidden within @code{read-buffer}
+(@pxref{High-Level Completion}).
 @end defvar
 
 @defvar completion-regexp-list
@@ -871,15 +875,33 @@
 @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
address@hidden, the user can exit with any input, but she will
-be asked for a confirmation if the input is not an element of
address@hidden  Any other value of @var{require-match} behaves like
address@hidden, 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:
+
address@hidden @bullet
address@hidden
+If @code{nil}, the usual minibuffer exit commands work regardless of
+the input in the minibuffer.
+
address@hidden
+If @code{t}, the usual minibuffer exit commands won't exit unless the
+input completes to an element of @var{collection}.
+
address@hidden
+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}.
+
address@hidden
+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
address@hidden) and the resulting input is
+not an element of @var{collection}.  @xref{Completion Commands}.
+
address@hidden
+Any other value of @var{require-match} behaves like @code{t}, except
+that the exit commands won't exit if it performs completion.
address@hidden 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 @@
 @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 @@
 @end defvar
 
 @defvar minibuffer-completion-confirm
-When the value of this variable is address@hidden, Emacs asks for
-confirmation of a completion before exiting the minibuffer.
address@hidden binds this variable, and the function
address@hidden 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
address@hidden
address@hidden defvar
+
address@hidden 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 @@
 reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
address@hidden read-buffer prompt &optional default existing
address@hidden 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 address@hidden,
@@ -1127,17 +1159,12 @@
 @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 address@hidden, 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,
address@hidden 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
address@hidden  @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 @@
 @code{iswitchb} package to read it.
 @end defvar
 
address@hidden read-buffer-completion-ignore-case
+If this variable is address@hidden, @code{read-buffer} ignores case
+when performing completion.
address@hidden 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 @@
 for reading file names and shell commands.  They provide special
 features including automatic insertion of the default directory.
 
address@hidden read-file-name prompt &optional directory default existing 
initial predicate
address@hidden 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 address@hidden, 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
address@hidden also requires confirmation after completion.  If
address@hidden is @code{nil}, then the name of a nonexistent file is
-acceptable.
+The optional argument @var{require-match} has the same meaning as in
address@hidden  @xref{Minibuffer Completion}.
 
 @code{read-file-name} uses
 @code{minibuffer-local-filename-completion-map} as the keymap if
address@hidden is @code{nil}, and uses
address@hidden if @var{existing} is
address@hidden  @xref{Completion Commands}.
address@hidden is @code{nil}, and uses
address@hidden if @var{require-match}
+is address@hidden  @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 @@
 minibuffer contents are always non-empty if
 @code{insert-default-directory} is address@hidden, 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
 address@hidden, 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 @@
 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
address@hidden  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 address@hidden, it specifies a function of one
 argument that decides which file names are acceptable completion
@@ -1420,7 +1447,7 @@
 when performing completion.
 @end defvar
 
address@hidden read-directory-name prompt &optional directory default existing 
initial
address@hidden 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.