Add 2012 to FSF copyright years for Emacs files

[bpt/emacs.git] / doc / lispref / minibuf.texi

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 84f2a4f..e300847 100644 (file)
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c   2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
+@c   Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/minibuf
 @node Minibuffers, Command Loop, Read and Print, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/minibuf
 @node Minibuffers, Command Loop, Read and Print, Top


@@ -22,13 +22,13 @@ argument.
 * Intro to Minibuffers::      Basic information about minibuffers.
 * Text from Minibuffer::      How to read a straight text string.
 * Object from Minibuffer::    How to read a Lisp object or expression.
 * Intro to Minibuffers::      Basic information about minibuffers.
 * Text from Minibuffer::      How to read a straight text string.
 * Object from Minibuffer::    How to read a Lisp object or expression.

-* Minibuffer History::       Recording previous minibuffer inputs
-                               so the user can reuse them.
+* Minibuffer History::        Recording previous minibuffer inputs
+                                so the user can reuse them.

 * 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.
 * 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.
-* Reading a Password::       Reading a password from the terminal.
+* Multiple Queries::          Asking a series of similar questions.
+* Reading a Password::        Reading a password from the terminal.

 * Minibuffer Commands::       Commands used as key bindings in minibuffers.
 * Minibuffer Contents::       How such commands access the minibuffer text.
 * Minibuffer Windows::        Operating on the special minibuffer windows.
 * Minibuffer Commands::       Commands used as key bindings in minibuffers.
 * Minibuffer Contents::       How such commands access the minibuffer text.
 * Minibuffer Windows::        Operating on the special minibuffer windows.


@@ -56,17 +56,15 @@ read-only so you won't accidentally delete or change it.  It is also
 marked as a field (@pxref{Fields}), so that certain motion functions,
 including @code{beginning-of-line}, @code{forward-word},
 @code{forward-sentence}, and @code{forward-paragraph}, stop at the
 marked as a field (@pxref{Fields}), so that certain motion functions,
 including @code{beginning-of-line}, @code{forward-word},
 @code{forward-sentence}, and @code{forward-paragraph}, stop at the

-boundary between the prompt and the actual text.  (In older Emacs
-versions, the prompt was displayed using a special mechanism and was not
-part of the buffer contents.)
+boundary between the prompt and the actual text.

 
   The minibuffer's window is normally a single line; it grows
 
   The minibuffer's window is normally a single line; it grows

-automatically if necessary if the contents require more space.  You can
-explicitly resize it temporarily with the window sizing commands; it
-reverts to its normal size when the minibuffer is exited.  You can
-resize it permanently by using the window sizing commands in the frame's
-other window, when the minibuffer is not active.  If the frame contains
-just a minibuffer, you can change the minibuffer's size by changing the
+automatically if the contents require more space.  You can explicitly
+resize it temporarily with the window sizing commands; it reverts to
+its normal size when the minibuffer is exited.  You can resize it
+permanently by using the window sizing commands in the frame's other
+window, when the minibuffer is not active.  If the frame contains just
+a minibuffer, you can change the minibuffer's size by changing the

 frame's size.
 
   Use of the minibuffer reads input events, and that alters the values
 frame's size.
 
   Use of the minibuffer reads input events, and that alters the values


@@ -74,16 +72,17 @@ of variables such as @code{this-command} and @code{last-command}
 (@pxref{Command Loop Info}).  Your program should bind them around the
 code that uses the minibuffer, if you do not want that to change them.
 
 (@pxref{Command Loop Info}).  Your program should bind them around the
 code that uses the minibuffer, if you do not want that to change them.
 

-  If a command uses a minibuffer while there is an active minibuffer,
-this is called a @dfn{recursive minibuffer}.  The first minibuffer is
-named @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
-incrementing the number at the end of the name.  (The names begin with a
-space so that they won't show up in normal buffer lists.)  Of several
-recursive minibuffers, the innermost (or most recently entered) is the
-active minibuffer.  We usually call this ``the'' minibuffer.  You can
-permit or forbid recursive minibuffers by setting the variable
-@code{enable-recursive-minibuffers} or by putting properties of that
-name on command symbols (@pxref{Recursive Mini}).
+  Under some circumstances, a command can use a minibuffer even if
+there is an active minibuffer; such minibuffers are called a
+@dfn{recursive minibuffer}.  The first minibuffer is named
+@w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
+incrementing the number at the end of the name.  (The names begin with
+a space so that they won't show up in normal buffer lists.)  Of
+several recursive minibuffers, the innermost (or most recently
+entered) is the active minibuffer.  We usually call this ``the''
+minibuffer.  You can permit or forbid recursive minibuffers by setting
+the variable @code{enable-recursive-minibuffers}, or by putting
+properties of that name on command symbols (@xref{Recursive Mini}.)

 
   Like other buffers, a minibuffer uses a local keymap
 (@pxref{Keymaps}) to specify special key bindings.  The function that
 
   Like other buffers, a minibuffer uses a local keymap
 (@pxref{Keymaps}) to specify special key bindings.  The function that


@@ -99,13 +98,13 @@ was supplied when Emacs was started.
 @node Text from Minibuffer
 @section Reading Text Strings with the Minibuffer
 
 @node Text from Minibuffer
 @section Reading Text Strings with the Minibuffer
 

-  Most often, the minibuffer is used to read text as a string.  It can
-also be used to read a Lisp object in textual form.  The most basic
-primitive for minibuffer input is @code{read-from-minibuffer}; it can
-do either one.  Regular expressions (@pxref{Regular Expressions}) are
-a special kind of strings; use @code{read-regexp} for their minibuffer
-input.  There are also specialized commands for reading commands,
-variables, file names, etc.@: (@pxref{Completion}).
+  The most basic primitive for minibuffer input is
+@code{read-from-minibuffer}, which can be used to read either a string
+or a Lisp object in textual form.  The function @code{read-regexp} is
+used for reading regular expressions (@pxref{Regular Expressions}),
+which are a special kind of string.  There are also specialized
+functions for reading commands, variables, file names, etc.@:
+(@pxref{Completion}).

 
   In most cases, you should not call minibuffer input functions in the
 middle of a Lisp function.  Instead, do all minibuffer input as part of
 
   In most cases, you should not call minibuffer input functions in the
 middle of a Lisp function.  Instead, do all minibuffer input as part of


@@ -113,7 +112,7 @@ reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
 specification.  @xref{Defining Commands}.
 
 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method

-This function is the most general way to get input through the
+This function is the most general way to get input from the

 minibuffer.  By default, it accepts arbitrary text and returns it as a
 string; however, if @var{read} is non-@code{nil}, then it uses
 @code{read} to convert the text into a Lisp object (@pxref{Input
 minibuffer.  By default, it accepts arbitrary text and returns it as a
 string; however, if @var{read} is non-@code{nil}, then it uses
 @code{read} to convert the text into a Lisp object (@pxref{Input


@@ -434,18 +433,17 @@ expression, thus moving point forward one word.
 @cindex minibuffer history
 @cindex history list
 
 @cindex minibuffer history
 @cindex history list
 

-  A @dfn{minibuffer history list} records previous minibuffer inputs so
-the user can reuse them conveniently.  A history list is actually a
-symbol, not a list; it is a variable whose value is a list of strings
-(previous inputs), most recent first.
+  A @dfn{minibuffer history list} records previous minibuffer inputs
+so the user can reuse them conveniently.  It is a variable whose value
+is a list of strings (previous inputs), most recent first.

 
 

-  There are many separate history lists, used for different kinds of
-inputs.  It's the Lisp programmer's job to specify the right history
-list for each use of the minibuffer.
+  There are many separate minibuffer history lists, used for different
+kinds of inputs.  It's the Lisp programmer's job to specify the right
+history list for each use of the minibuffer.

 
 

-  You specify the history list with the optional @var{hist} argument
-to either @code{read-from-minibuffer} or @code{completing-read}.  Here
-are the possible values for it:
+  You specify a minibuffer history list with the optional @var{hist}
+argument to @code{read-from-minibuffer} or @code{completing-read}.
+Here are the possible values for it:

 
 @table @asis
 @item @var{variable}
 
 @table @asis
 @item @var{variable}


@@ -509,19 +507,19 @@ This lets Lisp programs explicitly manage input history by using
 set to a non-@code{nil} value.
 @end defvar
 
 set to a non-@code{nil} value.
 @end defvar
 

-@defvar history-length
+@defopt history-length

 The value of this variable specifies the maximum length for all
 history lists that don't specify their own maximum lengths.  If the
 The value of this variable specifies the maximum length for all
 history lists that don't specify their own maximum lengths.  If the

-value is @code{t}, that means there no maximum (don't delete old
+value is @code{t}, that means there is no maximum (don't delete old

 elements).  The value of @code{history-length} property of the history
 list variable's symbol, if set, overrides this variable for that
 particular history list.
 elements).  The value of @code{history-length} property of the history
 list variable's symbol, if set, overrides this variable for that
 particular history list.

-@end defvar
+@end defopt

 
 

-@defvar history-delete-duplicates
+@defopt history-delete-duplicates

 If the value of this variable is @code{t}, that means when adding a
 new history element, all previous identical elements are deleted.
 If the value of this variable is @code{t}, that means when adding a
 new history element, all previous identical elements are deleted.

-@end defvar
+@end defopt

 
   Here are some of the standard minibuffer history list variables:
 
 
   Here are some of the standard minibuffer history list variables:
 


@@ -627,52 +625,44 @@ for reading certain kinds of names with completion.
 
 @menu
 * Basic Completion::       Low-level functions for completing strings.
 
 @menu
 * Basic Completion::       Low-level functions for completing strings.

-                             (These are too low level to use the minibuffer.)

 * Minibuffer Completion::  Invoking the minibuffer with completion.
 * Completion Commands::    Minibuffer commands that do completion.
 * High-Level Completion::  Convenient special cases of completion
 * Minibuffer Completion::  Invoking the minibuffer with completion.
 * Completion Commands::    Minibuffer commands that do completion.
 * High-Level Completion::  Convenient special cases of completion

-                             (reading buffer name, file name, etc.)
+                             (reading buffer name, file name, etc.).

 * Reading File Names::     Using completion to read file names and
                              shell commands.
 * Reading File Names::     Using completion to read file names and
                              shell commands.

+* Completion Styles::      Specifying rules for performing completion.

 * Programmed Completion::  Writing your own completion-function.
 @end menu
 
 @node Basic Completion
 @subsection Basic Completion Functions
 
 * Programmed Completion::  Writing your own completion-function.
 @end menu
 
 @node Basic Completion
 @subsection Basic Completion Functions
 

-  The completion functions @code{try-completion},
-@code{all-completions} and @code{test-completion} have nothing in
-themselves to do with minibuffers.  We describe them in this chapter
-so as to keep them near the higher-level completion features that do
-use the minibuffer.
-
-  If you store a completion alist in a variable, you should mark the
-variable as ``risky'' with a non-@code{nil}
-@code{risky-local-variable} property.
+  The following completion functions have nothing in themselves to do
+with minibuffers.  We describe them here to keep them near the
+higher-level completion features that do use the minibuffer.

 
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
 completions of @var{string} in @var{collection}.  The value of
 
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
 completions of @var{string} in @var{collection}.  The value of

-@var{collection} must be a list of strings or symbols, an alist, an
-obarray, a hash table, or a function that implements a virtual set of
-strings (see below).
+@var{collection} must be a list of strings, an alist whose keys are
+strings or symbols, an obarray, a hash table, or a completion function
+(@pxref{Programmed Completion}).

 
 Completion compares @var{string} against each of the permissible
 
 Completion compares @var{string} against each of the permissible

-completions specified by @var{collection}; if the beginning of the
-permissible completion equals @var{string}, it matches.  If no permissible
-completions match, @code{try-completion} returns @code{nil}.  If only
-one permissible completion matches, and the match is exact, then
-@code{try-completion} returns @code{t}.  Otherwise, the value is the
-longest initial sequence common to all the permissible completions that
-match.
+completions specified by @var{collection}.  If no permissible
+completions match, @code{try-completion} returns @code{nil}.  If there
+is just one matching completion, and the match is exact, it returns
+@code{t}.  Otherwise, it returns the longest initial sequence common
+to all possible matching completions.

 
 If @var{collection} is an alist (@pxref{Association Lists}), the
 permissible completions are the elements of the alist that are either
 
 If @var{collection} is an alist (@pxref{Association Lists}), the
 permissible completions are the elements of the alist that are either

-strings, symbols, or conses whose @sc{car} is a string or symbol.
+strings, or conses whose @sc{car} is a string or symbol.

 Symbols are converted to strings using @code{symbol-name}.  Other
 elements of the alist are ignored. (Remember that in Emacs Lisp, the
 elements of alists do not @emph{have} to be conses.)  In particular, a
 Symbols are converted to strings using @code{symbol-name}.  Other
 elements of the alist are ignored. (Remember that in Emacs Lisp, the
 elements of alists do not @emph{have} to be conses.)  In particular, a

-list of strings or symbols is allowed, even though we usually do not
+list of strings is allowed, even though we usually do not

 think of such lists as alists.
 
 @cindex obarray in completion
 think of such lists as alists.
 
 @cindex obarray in completion


@@ -688,13 +678,13 @@ Also, you cannot intern a given symbol in more than one obarray.
 If @var{collection} is a hash table, then the keys that are strings
 are the possible completions.  Other keys are ignored.
 
 If @var{collection} is a hash table, then the keys that are strings
 are the possible completions.  Other keys are ignored.
 

-You can also use a symbol that is a function as @var{collection}.  Then
-the function is solely responsible for performing completion;
+You can also use a function as @var{collection}.
+Then the function is solely responsible for performing completion;

 @code{try-completion} returns whatever this function returns.  The
 function is called with three arguments: @var{string}, @var{predicate}
 @code{try-completion} returns whatever this function returns.  The
 function is called with three arguments: @var{string}, @var{predicate}

-and @code{nil}.  (The reason for the third argument is so that the same
+and @code{nil} (the reason for the third argument is so that the same

 function can be used in @code{all-completions} and do the appropriate
 function can be used in @code{all-completions} and do the appropriate

-thing in either case.)  @xref{Programmed Completion}.
+thing in either case).  @xref{Programmed Completion}.

 
 If the argument @var{predicate} is non-@code{nil}, then it must be a
 function of one argument, unless @var{collection} is a hash table, in
 
 If the argument @var{predicate} is non-@code{nil}, then it must be a
 function of one argument, unless @var{collection} is a hash table, in


@@ -769,10 +759,11 @@ This function returns a list of all possible completions of
 @var{string}.  The arguments to this function (aside from
 @var{nospace}) are the same as those of @code{try-completion}.  Also,
 this function uses @code{completion-regexp-list} in the same way that
 @var{string}.  The arguments to this function (aside from
 @var{nospace}) are the same as those of @code{try-completion}.  Also,
 this function uses @code{completion-regexp-list} in the same way that

-@code{try-completion} does.  The optional argument @var{nospace} only
-matters if @var{string} is the empty string.  In that case, if
-@var{nospace} is non-@code{nil}, completions that start with a space
-are ignored.
+@code{try-completion} does.
+
+The optional argument @var{nospace} is obsolete.  If it is
+non-@code{nil}, completions that start with a space are ignored unless
+@var{string} starts with a space.

 
 If @var{collection} is a function, it is called with three arguments:
 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
 
 If @var{collection} is a function, it is called with three arguments:
 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}


@@ -822,9 +813,37 @@ the values @var{string}, @var{predicate} and @code{lambda}; whatever
 it returns, @code{test-completion} returns in turn.
 @end defun
 
 it returns, @code{test-completion} returns in turn.
 @end defun
 

+@defun completion-boundaries string collection predicate suffix
+This function returns the boundaries of the field on which @var{collection}
+will operate, assuming that @var{string} holds the text before point
+and @var{suffix} holds the text after point.
+
+Normally completion operates on the whole string, so for all normal
+collections, this will always return @code{(0 . (length
+@var{suffix}))}.  But more complex completion such as completion on
+files is done one field at a time.  For example, completion of
+@code{"/usr/sh"} will include @code{"/usr/share/"} but not
+@code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
+Also @code{all-completions} on @code{"/usr/sh"} will not include
+@code{"/usr/share/"} but only @code{"share/"}.  So if @var{string} is
+@code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
+@code{completion-boundaries} will return @code{(5 . 1)} which tells us
+that the @var{collection} will only return completion information that
+pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
+@end defun
+
+If you store a completion alist in a variable, you should mark the
+variable as ``risky'' with a non-@code{nil}
+@code{risky-local-variable} property.  @xref{File Local Variables}.
+

 @defvar completion-ignore-case
 @defvar completion-ignore-case

-If the value of this variable is non-@code{nil}, Emacs does not
-consider case significant in completion.
+If the value of this variable is non-@code{nil}, case is not
+considered significant in completion.  Within @code{read-file-name},
+this variable is overridden by
+@code{read-file-name-completion-ignore-case} (@pxref{Reading File
+Names}); within @code{read-buffer}, it is overridden by
+@code{read-buffer-completion-ignore-case} (@pxref{High-Level
+Completion}).

 @end defvar
 
 @defvar completion-regexp-list
 @end defvar
 
 @defvar completion-regexp-list


@@ -850,6 +869,23 @@ Here is an example of use:
 @end smallexample
 @end defmac
 
 @end smallexample
 @end defmac
 

+The function @code{completion-in-region} provides a convenient way to
+perform completion on an arbitrary stretch of text in an Emacs buffer:
+
+@defun completion-in-region start end collection &optional predicate
+This function completes the text in the current buffer between the
+positions @var{start} and @var{end}, using @var{collection}.  The
+argument @var{collection} has the same meaning as in
+@code{try-completion} (@pxref{Basic Completion}).
+
+This function inserts the completion text directly into the current
+buffer.  Unlike @code{completing-read} (@pxref{Minibuffer
+Completion}), it does not activate the minibuffer.
+
+For this function to work, point must be somewhere between @var{start}
+and @var{end}.
+@end defun
+

 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 @cindex minibuffer completion
 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 @cindex minibuffer completion


@@ -864,22 +900,40 @@ providing completion.  It activates the minibuffer with prompt
 @var{prompt}, which must be a string.
 
 The actual completion is done by passing @var{collection} and
 @var{prompt}, which must be a string.
 
 The actual completion is done by passing @var{collection} and

-@var{predicate} to the function @code{try-completion}.  This happens
-in certain commands bound in the local keymaps used for completion.
-Some of these commands also call @code{test-completion}.  Thus, if
-@var{predicate} is non-@code{nil}, it should be compatible with
-@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.
+@var{predicate} to the function @code{try-completion} (@pxref{Basic
+Completion}).  This happens in certain commands bound in the local
+keymaps used for completion.  Some of these commands also call
+@code{test-completion}.  Thus, if @var{predicate} is non-@code{nil},
+it should be compatible with @var{collection} and
+@code{completion-ignore-case}.  @xref{Definition of test-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
 
 However, empty input is always permitted, regardless of the value of
 @var{require-match}; in that case, @code{completing-read} returns the


@@ -948,12 +1002,7 @@ They are described in the following section.
 @subsection Minibuffer Commands that Do Completion
 
   This section describes the keymaps, commands and user options used
 @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
 
 @defvar minibuffer-completion-table
 The value of this variable is the collection used for completion in


@@ -969,10 +1018,25 @@ minibuffer completion functions.
 @end defvar
 
 @defvar minibuffer-completion-confirm
 @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
 @end defvar
 
 @deffn Command minibuffer-complete-word


@@ -1113,7 +1177,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}.
 
 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},
 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 +1191,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}).
 
 @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
 
 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
 @samp{minibuffer.texi}, so that name is the value.
 
 @example


@@ -1161,12 +1220,18 @@ Buffer name (default foo): @point{}
 @end example
 @end defun
 
 @end example
 @end defun
 

-@defvar read-buffer-function
-This variable specifies how to read buffer names.  For example, if you
-set this variable to @code{iswitchb-read-buffer}, all Emacs commands
-that call @code{read-buffer} to read a buffer name will actually use the
-@code{iswitchb} package to read it.
-@end defvar
+@defopt read-buffer-function
+This variable specifies how to read buffer names.  The function is
+called with the arguments passed to @code{read-buffer}.  For example,
+if you set this variable to @code{iswitchb-read-buffer}, all Emacs
+commands that call @code{read-buffer} to read a buffer name will
+actually use the @code{iswitchb} package to read it.
+@end defopt
+
+@defopt read-buffer-completion-ignore-case
+If this variable is non-@code{nil}, @code{read-buffer} ignores case
+when performing completion.
+@end defopt

 
 @defun read-command prompt &optional default
 This function reads the name of a command and returns it as a Lisp
 
 @defun read-command prompt &optional default
 This function reads the name of a command and returns it as a Lisp


@@ -1285,7 +1350,7 @@ invalid color name was specified, this function signals an error,
 except that empty color names are allowed when @code{allow-empty} is
 non-@code{nil} and the user enters null input.
 
 except that empty color names are allowed when @code{allow-empty} is
 non-@code{nil} and the user enters null input.
 

-Interactively, or when @var{display} is non-@code{nill}, the return
+Interactively, or when @var{display} is non-@code{nil}, the return

 value is also displayed in the echo area.
 @end deffn
 
 value is also displayed in the echo area.
 @end deffn
 


@@ -1298,35 +1363,44 @@ and @code{read-input-method-name}, in @ref{Input Methods}.
 @cindex read file names
 @cindex prompt for file name
 
 @cindex read file names
 @cindex prompt for file name
 

-  Here is a couple of other high-level completion functions, designed
-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
-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.
-
-@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}.
+  The high-level completion functions @code{read-file-name},
+@code{read-directory-name}, and @code{read-shell-command} are designed
+to read file names, directory names, and shell commands respectively.
+They provide special features, including automatic insertion of the
+default directory.
+
+@defun read-file-name prompt &optional directory default require-match initial predicate
+This function reads a file name, prompting with @var{prompt} and
+providing completion.
+
+As an exception, this function reads a file name using a graphical
+file dialog instead of the minibuffer, if (i) it is invoked via a
+mouse command, and (ii) the selected frame is on a graphical display
+supporting such dialogs, and (iii) the variable @code{use-dialog-box}
+is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
+Emacs Manual}), and (iv) the @var{directory} argument, described
+below, does not specify a remote file (@pxref{Remote Files,, Remote
+Files, emacs, The GNU Emacs Manual}).  The exact behavior when using a
+graphical file dialog is platform-dependent.  Here, we simply document
+the behavior when using the minibuffer.
+
+@code{read-file-name} does not automatically expand the returned file
+name.  You must call @code{expand-file-name} yourself if an absolute
+file name is required.
+
+The optional argument @var{require-match} has the same meaning as in
+@code{completing-read}.  @xref{Minibuffer Completion}.  If
+@var{require-match} is @code{nil}, the local keymap in the minibuffer
+is @code{minibuffer-local-filename-completion-map}; otherwise, it is
+@code{minibuffer-local-filename-must-match-map}.  @xref{Completion
+Commands}.

 
 The argument @var{directory} specifies the directory to use for
 
 The argument @var{directory} specifies the directory to use for

-completion of relative file names.  It should be an absolute directory
+completing relative file names.  It should be an absolute directory

 name.  If @code{insert-default-directory} is non-@code{nil},
 @var{directory} is also inserted in the minibuffer as initial input.
 It defaults to the current buffer's value of @code{default-directory}.
 
 name.  If @code{insert-default-directory} is non-@code{nil},
 @var{directory} is also inserted in the minibuffer as initial input.
 It defaults to the current buffer's value of @code{default-directory}.
 

-@c Emacs 19 feature

 If you specify @var{initial}, that is an initial file name to insert
 in the buffer (after @var{directory}, if that is inserted).  In this
 case, point goes at the beginning of @var{initial}.  The default for
 If you specify @var{initial}, that is an initial file name to insert
 in the buffer (after @var{directory}, if that is inserted).  In this
 case, point goes at the beginning of @var{initial}.  The default for


@@ -1341,7 +1415,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
 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
 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,20 +1435,16 @@ 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 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
 possibilities.  A file name is an acceptable value if @var{predicate}
 returns non-@code{nil} for it.
 
 
 If @var{predicate} is non-@code{nil}, it specifies a function of one
 argument that decides which file names are acceptable completion
 possibilities.  A file name is an acceptable value if @var{predicate}
 returns non-@code{nil} for it.
 

-@code{read-file-name} does not automatically expand file names.  You
-must call @code{expand-file-name} yourself if an absolute file name is
-required.
-
-Here is an example:
+Here is an example of using @code{read-file-name}:

 
 @example
 @group
 
 @example
 @group


@@ -1415,12 +1485,12 @@ called, it calls this function with the supplied arguments instead of
 doing its usual work.
 @end defvar
 
 doing its usual work.
 @end defvar
 

-@defvar read-file-name-completion-ignore-case
+@defopt read-file-name-completion-ignore-case

 If this variable is non-@code{nil}, @code{read-file-name} ignores case
 when performing completion.
 If this variable is non-@code{nil}, @code{read-file-name} ignores case
 when performing completion.

-@end defvar
+@end defopt

 
 

-@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.
 
 This function is like @code{read-file-name} but allows only directory
 names as completion possibilities.
 


@@ -1505,20 +1575,75 @@ This keymap is used by @code{read-shell-command} for completing
 command and file names that are part of a shell command.
 @end defvar
 
 command and file names that are part of a shell command.
 @end defvar
 

+@node Completion Styles
+@subsection Completion Styles
+@cindex completion styles
+
+  A @dfn{completion style} is a set of rules for generating
+completions.  The user option @code{completion-styles} stores a list
+of completion styles, which are represented by symbols.
+
+@defopt completion-styles
+This is a list of completion style symbols to use for performing
+completion.  Each completion style in this list must be defined in
+@code{completion-styles-alist}.
+@end defopt
+
+@defvar completion-styles-alist
+This variable stores a list of available completion styles.  Each
+element in the list must have the form @samp{(@var{name}
+@var{try-completion} @var{all-completions})}.  Here, @var{name} is the
+name of the completion style (a symbol), which may be used in
+@code{completion-styles-alist} to refer to this style.
+
+@var{try-completion} is the function that does the completion, and
+@var{all-completions} is the function that lists the completions.
+These functions should accept four arguments: @var{string},
+@var{collection}, @var{predicate}, and @var{point}.  The @var{string},
+@var{collection}, and @var{predicate} arguments have the same meanings
+as in @code{try-completion} (@pxref{Basic Completion}), and the
+@var{point} argument is the position of point within @var{string}.
+Each function should return a non-@code{nil} value if it performed its
+job, and @code{nil} if it did not (e.g., if there is no way to
+complete @var{string} according to the completion style).
+
+When the user calls a completion command, such as
+@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
+for the first style listed in @code{completion-styles} and calls its
+@var{try-completion} function.  If this function returns @code{nil},
+Emacs moves to the next completion style listed in
+@code{completion-styles} and calls its @var{try-completion} function,
+and so on until one of the @var{try-completion} functions successfully
+performs completion and returns a non-@code{nil} value.  A similar
+procedure is used for listing completions, via the
+@var{all-completions} functions.
+@end defvar
+
+  By default, @code{completion-styles-alist} contains five pre-defined
+completion styles: @code{basic}, a basic completion style;
+@code{partial-completion}, which does partial completion (completing
+each word in the input separately); @code{emacs22}, which performs
+completion according to the rules used in Emacs 22; @code{emacs21},
+which performs completion according to the rules used in Emacs 21; and
+@code{initials}, which completes acronyms and initialisms.
+

 @node Programmed Completion
 @subsection Programmed Completion
 @cindex programmed completion
 
 @node Programmed Completion
 @subsection Programmed Completion
 @cindex programmed completion
 

-  Sometimes it is not possible to create an alist or an obarray
-containing all the intended possible completions.  In such a case, you
-can supply your own function to compute the completion of a given string.
-This is called @dfn{programmed completion}.
+  Sometimes it is not possible or convenient to create an alist or
+an obarray containing all the intended possible completions ahead
+of time.  In such a case, you can supply your own function to compute
+the completion of a given string.  This is called @dfn{programmed
+completion}.  Emacs uses programmed completion when completing file
+names (@pxref{File Name Completion}), among many other cases.

 
 

-  To use this feature, pass a symbol with a function definition as the
-@var{collection} argument to @code{completing-read}.  The function
+  To use this feature, pass a function as the @var{collection}
+argument to @code{completing-read}.  The function

 @code{completing-read} arranges to pass your completion function along
 @code{completing-read} arranges to pass your completion function along

-to @code{try-completion} and @code{all-completions}, which will then let
-your function do all the work.
+to @code{try-completion}, @code{all-completions}, and other basic
+completion functions, which will then let your function do all
+the work.

 
   The completion function should accept three arguments:
 
 
   The completion function should accept three arguments:
 


@@ -1532,10 +1657,14 @@ none.  Your function should call the predicate for each possible match,
 and ignore the possible match if the predicate returns @code{nil}.
 
 @item
 and ignore the possible match if the predicate returns @code{nil}.
 
 @item

-A flag specifying the type of operation.
+A flag specifying the type of operation.  The best way to think about
+it is that the function stands for an object (in the
+``object-oriented'' sense of the word), and this third argument
+specifies which method to run.

 @end itemize
 
 @end itemize
 

-  There are three flag values for three operations:
+  There are currently four methods, i.e. four flag values, one for
+each of the four different basic operations:

 
 @itemize @bullet
 @item
 
 @itemize @bullet
 @item


@@ -1557,18 +1686,14 @@ string.
 @code{lambda} specifies @code{test-completion}.  The completion
 function should return @code{t} if the specified string is an exact
 match for some possibility; @code{nil} otherwise.
 @code{lambda} specifies @code{test-completion}.  The completion
 function should return @code{t} if the specified string is an exact
 match for some possibility; @code{nil} otherwise.

-@end itemize
-
-  It would be consistent and clean for completion functions to allow
-lambda expressions (lists that are functions) as well as function
-symbols as @var{collection}, but this is impossible.  Lists as
-completion tables already have other meanings, and it would be
-unreliable to treat one differently just because it is also a possible
-function.  So you must arrange for any function you wish to use for
-completion to be encapsulated in a symbol.

 
 

-  Emacs uses programmed completion when completing file names.
-@xref{File Name Completion}.
+@item
+@code{(boundaries . SUFFIX)} specifies @code{completion-boundaries}.
+The function should return a value of the form @code{(boundaries
+START . END)} where START is the position of the beginning boundary
+in the string to complete, and END is the position of the end boundary
+in SUFFIX.
+@end itemize

 
 @defun completion-table-dynamic function
 This function is a convenient way to write a function that can act as
 
 @defun completion-table-dynamic function
 This function is a convenient way to write a function that can act as


@@ -1579,6 +1704,19 @@ possible completions of it.  You can think of
 and the interface for programmed completion functions.
 @end defun
 
 and the interface for programmed completion functions.
 @end defun
 

+@defvar completion-annotate-function
+The value of this variable, if non-@code{nil}, should be a function
+for ``annotating'' the entries in the @samp{*Completions*} buffer.
+The function should accept a single argument, the completion string
+for an entry.  It should return an additional string to display next
+to that entry in the @samp{*Completions*} buffer, or @code{nil} if no
+additional string is to be displayed.
+
+The function can determine the collection used for the current
+completion via the variable @code{minibuffer-completion-table}
+(@pxref{Completion Commands}).
+@end defvar
+

 @node Yes-or-No Queries
 @section Yes-or-No Queries
 @cindex asking the user questions
 @node Yes-or-No Queries
 @section Yes-or-No Queries
 @cindex asking the user questions


@@ -1851,7 +1989,7 @@ keys in minibuffer local keymaps.
 
 @deffn Command self-insert-and-exit
 This command exits the active minibuffer after inserting the last
 
 @deffn Command self-insert-and-exit
 This command exits the active minibuffer after inserting the last

-character typed on the keyboard (found in @code{last-command-char};
+character typed on the keyboard (found in @code{last-command-event};

 @pxref{Command Loop Info}).
 @end deffn
 
 @pxref{Command Loop Info}).
 @end deffn
 


@@ -2046,12 +2184,10 @@ windows.  If a float, it specifies a fraction of the height of the
 frame.  If an integer, it specifies a number of lines.
 @end defopt
 
 frame.  If an integer, it specifies a number of lines.
 @end defopt
 

-@defun minibuffer-message string
+@defun minibuffer-message string &rest args

 This function displays @var{string} temporarily at the end of the
 minibuffer text, for two seconds, or until the next input event
 This function displays @var{string} temporarily at the end of the
 minibuffer text, for two seconds, or until the next input event

-arrives, whichever comes first.
+arrives, whichever comes first.  If @var{args} is non-@code{nil}, the
+actual message is obtained by passing @var{string} and @var{args}
+through @code{format}.  @xref{Formatting Strings}.

 @end defun
 @end defun

-
-@ignore
-   arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
-@end ignore