changeset 84087:aa6ce8057bdb

Move here from ../../lispref

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/lispref/minibuf.texi	Thu Sep 06 04:21:58 2007 +0000
@@ -0,0 +1,1964 @@
+@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 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/minibuf
+@node Minibuffers, Command Loop, Read and Print, Top
+@chapter Minibuffers
+@cindex arguments, reading
+@cindex complex arguments
+@cindex minibuffer
+
+  A @dfn{minibuffer} is a special buffer that Emacs commands use to
+read arguments more complicated than the single numeric prefix
+argument.  These arguments include file names, buffer names, and
+command names (as in @kbd{M-x}).  The minibuffer is displayed on the
+bottom line of the frame, in the same place as the echo area
+(@pxref{The Echo Area}), but only while it is in use for reading an
+argument.
+
+@menu
+* 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.
+* 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.
+* 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.
+* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
+* Minibuffer Misc::           Various customization hooks and variables.
+@end menu
+
+@node Intro to Minibuffers
+@section Introduction to Minibuffers
+
+  In most ways, a minibuffer is a normal Emacs buffer.  Most operations
+@emph{within} a buffer, such as editing commands, work normally in a
+minibuffer.  However, many operations for managing buffers do not apply
+to minibuffers.  The name of a minibuffer always has the form @w{@samp{
+*Minibuf-@var{number}*}}, and it cannot be changed.  Minibuffers are
+displayed only in special windows used only for minibuffers; these
+windows always appear at the bottom of a frame.  (Sometimes frames have
+no minibuffer window, and sometimes a special kind of frame contains
+nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
+
+  The text in the minibuffer always starts with the @dfn{prompt string},
+the text that was specified by the program that is using the minibuffer
+to tell the user what sort of input to type.  This text is marked
+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
+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.)
+
+  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
+frame's size.
+
+  Use of the minibuffer reads input events, and that alters the values
+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.
+
+  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}).
+
+  Like other buffers, a minibuffer uses a local keymap
+(@pxref{Keymaps}) to specify special key bindings.  The function that
+invokes the minibuffer also sets up its local map according to the job
+to be done.  @xref{Text from Minibuffer}, for the non-completion
+minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
+local maps for completion.
+
+  When Emacs is running in batch mode, any request to read from the
+minibuffer actually reads a line from the standard input descriptor that
+was supplied when Emacs was started.
+
+@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.  There are also specialized commands 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
+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
+This function is the most general way to get input through 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
+Functions}).
+
+The first thing this function does is to activate a minibuffer and
+display it with @var{prompt-string} as the prompt.  This value must be a
+string.  Then the user can edit text in the minibuffer.
+
+When the user types a command to exit the minibuffer,
+@code{read-from-minibuffer} constructs the return value from the text in
+the minibuffer.  Normally it returns a string containing that text.
+However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
+reads the text and returns the resulting Lisp object, unevaluated.
+(@xref{Input Functions}, for information about reading.)
+
+The argument @var{default} specifies a default value to make available
+through the history commands.  It should be a string, or @code{nil}.
+If non-@code{nil}, the user can access it using
+@code{next-history-element}, usually bound in the minibuffer to
+@kbd{M-n}.  If @var{read} is non-@code{nil}, then @var{default} is
+also used as the input to @code{read}, if the user enters empty input.
+(If @var{read} is non-@code{nil} and @var{default} is @code{nil}, empty
+input results in an @code{end-of-file} error.)  However, in the usual
+case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
+ignores @var{default} when the user enters empty input and returns an
+empty string, @code{""}.  In this respect, it is different from all
+the other minibuffer input functions in this chapter.
+
+If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
+use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
+value of @code{minibuffer-local-map} is used as the keymap.  Specifying
+a keymap is the most important way to customize the minibuffer for
+various applications such as completion.
+
+The argument @var{hist} specifies which history list variable to use
+for saving the input and for history commands used in the minibuffer.
+It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
+
+If the variable @code{minibuffer-allow-text-properties} is
+non-@code{nil}, then the string which is returned includes whatever text
+properties were present in the minibuffer.  Otherwise all the text
+properties are stripped when the value is returned.
+
+If the argument @var{inherit-input-method} is non-@code{nil}, then the
+minibuffer inherits the current input method (@pxref{Input Methods}) and
+the setting of @code{enable-multibyte-characters} (@pxref{Text
+Representations}) from whichever buffer was current before entering the
+minibuffer.
+
+Use of @var{initial-contents} is mostly deprecated; we recommend using
+a non-@code{nil} value only in conjunction with specifying a cons cell
+for @var{hist}.  @xref{Initial Input}.
+@end defun
+
+@defun read-string prompt &optional initial history default inherit-input-method
+This function reads a string from the minibuffer and returns it.  The
+arguments @var{prompt}, @var{initial}, @var{history} and
+@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
+The keymap used is @code{minibuffer-local-map}.
+
+The optional argument @var{default} is used as in
+@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
+specifies a default value to return if the user enters null input.  As
+in @code{read-from-minibuffer} it should be a string, or @code{nil},
+which is equivalent to an empty string.
+
+This function is a simplified interface to the
+@code{read-from-minibuffer} function:
+
+@smallexample
+@group
+(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
+@equiv{}
+(let ((value
+       (read-from-minibuffer @var{prompt} @var{initial} nil nil
+                             @var{history} @var{default} @var{inherit})))
+  (if (and (equal value "") @var{default})
+      @var{default}
+    value))
+@end group
+@end smallexample
+@end defun
+
+@defvar minibuffer-allow-text-properties
+If this variable is @code{nil}, then @code{read-from-minibuffer} strips
+all text properties from the minibuffer input before returning it.
+This variable also affects @code{read-string}.  However,
+@code{read-no-blanks-input} (see below), as well as
+@code{read-minibuffer} and related functions (@pxref{Object from
+Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
+functions that do minibuffer input with completion, discard text
+properties unconditionally, regardless of the value of this variable.
+@end defvar
+
+@defvar minibuffer-local-map
+This
+@anchor{Definition of minibuffer-local-map}
+@c avoid page break at anchor; work around Texinfo deficiency
+is the default local keymap for reading from the minibuffer.  By
+default, it makes the following bindings:
+
+@table @asis
+@item @kbd{C-j}
+@code{exit-minibuffer}
+
+@item @key{RET}
+@code{exit-minibuffer}
+
+@item @kbd{C-g}
+@code{abort-recursive-edit}
+
+@item @kbd{M-n}
+@itemx @key{DOWN}
+@code{next-history-element}
+
+@item @kbd{M-p}
+@itemx @key{UP}
+@code{previous-history-element}
+
+@item @kbd{M-s}
+@code{next-matching-history-element}
+
+@item @kbd{M-r}
+@code{previous-matching-history-element}
+@end table
+@end defvar
+
+@c In version 18, initial is required
+@c Emacs 19 feature
+@defun read-no-blanks-input prompt &optional initial inherit-input-method
+This function reads a string from the minibuffer, but does not allow
+whitespace characters as part of the input: instead, those characters
+terminate the input.  The arguments @var{prompt}, @var{initial}, and
+@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
+
+This is a simplified interface to the @code{read-from-minibuffer}
+function, and passes the value of the @code{minibuffer-local-ns-map}
+keymap as the @var{keymap} argument for that function.  Since the keymap
+@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
+possible to put a space into the string, by quoting it.
+
+This function discards text properties, regardless of the value of
+@code{minibuffer-allow-text-properties}.
+
+@smallexample
+@group
+(read-no-blanks-input @var{prompt} @var{initial})
+@equiv{}
+(let (minibuffer-allow-text-properties)
+  (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
+@end group
+@end smallexample
+@end defun
+
+@defvar minibuffer-local-ns-map
+This built-in variable is the keymap used as the minibuffer local keymap
+in the function @code{read-no-blanks-input}.  By default, it makes the
+following bindings, in addition to those of @code{minibuffer-local-map}:
+
+@table @asis
+@item @key{SPC}
+@cindex @key{SPC} in minibuffer
+@code{exit-minibuffer}
+
+@item @key{TAB}
+@cindex @key{TAB} in minibuffer
+@code{exit-minibuffer}
+
+@item @kbd{?}
+@cindex @kbd{?} in minibuffer
+@code{self-insert-and-exit}
+@end table
+@end defvar
+
+@node Object from Minibuffer
+@section Reading Lisp Objects with the Minibuffer
+
+  This section describes functions for reading Lisp objects with the
+minibuffer.
+
+@defun read-minibuffer prompt &optional initial
+This function reads a Lisp object using the minibuffer, and returns it
+without evaluating it.  The arguments @var{prompt} and @var{initial} are
+used as in @code{read-from-minibuffer}.
+
+This is a simplified interface to the
+@code{read-from-minibuffer} function:
+
+@smallexample
+@group
+(read-minibuffer @var{prompt} @var{initial})
+@equiv{}
+(let (minibuffer-allow-text-properties)
+  (read-from-minibuffer @var{prompt} @var{initial} nil t))
+@end group
+@end smallexample
+
+Here is an example in which we supply the string @code{"(testing)"} as
+initial input:
+
+@smallexample
+@group
+(read-minibuffer
+ "Enter an expression: " (format "%s" '(testing)))
+
+;; @r{Here is how the minibuffer is displayed:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Enter an expression: (testing)@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+The user can type @key{RET} immediately to use the initial input as a
+default, or can edit the input.
+@end defun
+
+@defun eval-minibuffer prompt &optional initial
+This function reads a Lisp expression using the minibuffer, evaluates
+it, then returns the result.  The arguments @var{prompt} and
+@var{initial} are used as in @code{read-from-minibuffer}.
+
+This function simply evaluates the result of a call to
+@code{read-minibuffer}:
+
+@smallexample
+@group
+(eval-minibuffer @var{prompt} @var{initial})
+@equiv{}
+(eval (read-minibuffer @var{prompt} @var{initial}))
+@end group
+@end smallexample
+@end defun
+
+@defun edit-and-eval-command prompt form
+This function reads a Lisp expression in the minibuffer, and then
+evaluates it.  The difference between this command and
+@code{eval-minibuffer} is that here the initial @var{form} is not
+optional and it is treated as a Lisp object to be converted to printed
+representation rather than as a string of text.  It is printed with
+@code{prin1}, so if it is a string, double-quote characters (@samp{"})
+appear in the initial text.  @xref{Output Functions}.
+
+The first thing @code{edit-and-eval-command} does is to activate the
+minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
+representation of @var{form} in the minibuffer, and lets the user edit it.
+When the user exits the minibuffer, the edited text is read with
+@code{read} and then evaluated.  The resulting value becomes the value
+of @code{edit-and-eval-command}.
+
+In the following example, we offer the user an expression with initial
+text which is a valid form already:
+
+@smallexample
+@group
+(edit-and-eval-command "Please edit: " '(forward-word 1))
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following appears in the minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Please edit: (forward-word 1)@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+Typing @key{RET} right away would exit the minibuffer and evaluate the
+expression, thus moving point forward one word.
+@code{edit-and-eval-command} returns @code{nil} in this example.
+@end defun
+
+@node Minibuffer History
+@section Minibuffer History
+@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.
+
+  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.
+
+  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:
+
+@table @asis
+@item @var{variable}
+Use @var{variable} (a symbol) as the history list.
+
+@item (@var{variable} . @var{startpos})
+Use @var{variable} (a symbol) as the history list, and assume that the
+initial history position is @var{startpos} (a nonnegative integer).
+
+Specifying 0 for @var{startpos} is equivalent to just specifying the
+symbol @var{variable}.  @code{previous-history-element} will display
+the most recent element of the history list in the minibuffer.  If you
+specify a positive @var{startpos}, the minibuffer history functions
+behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
+history element currently shown in the minibuffer.
+
+For consistency, you should also specify that element of the history
+as the initial minibuffer contents, using the @var{initial} argument
+to the minibuffer input function (@pxref{Initial Input}).
+@end table
+
+  If you don't specify @var{hist}, then the default history list
+@code{minibuffer-history} is used.  For other standard history lists,
+see below.  You can also create your own history list variable; just
+initialize it to @code{nil} before the first use.
+
+  Both @code{read-from-minibuffer} and @code{completing-read} add new
+elements to the history list automatically, and provide commands to
+allow the user to reuse items on the list.  The only thing your program
+needs to do to use a history list is to initialize it and to pass its
+name to the input functions when you wish.  But it is safe to modify the
+list by hand when the minibuffer input functions are not using it.
+
+  Emacs functions that add a new element to a history list can also
+delete old elements if the list gets too long.  The variable
+@code{history-length} specifies the maximum length for most history
+lists.  To specify a different maximum length for a particular history
+list, put the length in the @code{history-length} property of the
+history list symbol.  The variable @code{history-delete-duplicates}
+specifies whether to delete duplicates in history.
+
+@defun add-to-history history-var newelt &optional maxelt keep-all
+This function adds a new element @var{newelt}, if it isn't the empty
+string, to the history list stored in the variable @var{history-var},
+and returns the updated history list.  It limits the list length to
+the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
+(described below).  The possible values of @var{maxelt} have the same
+meaning as the values of @code{history-length}.
+
+Normally, @code{add-to-history} removes duplicate members from the
+history list if @code{history-delete-duplicates} is non-@code{nil}.
+However, if @var{keep-all} is non-@code{nil}, that says not to remove
+duplicates, and to add @var{newelt} to the list even if it is empty.
+@end defun
+
+@defvar history-add-new-input
+If the value of this variable is @code{nil}, standard functions that
+read from the minibuffer don't add new elements to the history list.
+This lets Lisp programs explicitly manage input history by using
+@code{add-to-history}.  By default, @code{history-add-new-input} is
+set to a non-@code{nil} value.
+@end defvar
+
+@defvar 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
+value is @code{t}, that means there 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.
+@end defvar
+
+@defvar 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.
+@end defvar
+
+  Here are some of the standard minibuffer history list variables:
+
+@defvar minibuffer-history
+The default history list for minibuffer history input.
+@end defvar
+
+@defvar query-replace-history
+A history list for arguments to @code{query-replace} (and similar
+arguments to other commands).
+@end defvar
+
+@defvar file-name-history
+A history list for file-name arguments.
+@end defvar
+
+@defvar buffer-name-history
+A history list for buffer-name arguments.
+@end defvar
+
+@defvar regexp-history
+A history list for regular expression arguments.
+@end defvar
+
+@defvar extended-command-history
+A history list for arguments that are names of extended commands.
+@end defvar
+
+@defvar shell-command-history
+A history list for arguments that are shell commands.
+@end defvar
+
+@defvar read-expression-history
+A history list for arguments that are Lisp expressions to evaluate.
+@end defvar
+
+@node Initial Input
+@section Initial Input
+
+Several of the functions for minibuffer input have an argument called
+@var{initial} or @var{initial-contents}.  This is a mostly-deprecated
+feature for specifying that the minibuffer should start out with
+certain text, instead of empty as usual.
+
+If @var{initial} is a string, the minibuffer starts out containing the
+text of the string, with point at the end, when the user starts to
+edit the text.  If the user simply types @key{RET} to exit the
+minibuffer, it will use the initial input string to determine the
+value to return.
+
+@strong{We discourage use of a non-@code{nil} value for
+@var{initial}}, because initial input is an intrusive interface.
+History lists and default values provide a much more convenient method
+to offer useful default inputs to the user.
+
+There is just one situation where you should specify a string for an
+@var{initial} argument.  This is when you specify a cons cell for the
+@var{hist} or @var{history} argument.  @xref{Minibuffer History}.
+
+@var{initial} can also be a cons cell of the form @code{(@var{string}
+. @var{position})}.  This means to insert @var{string} in the
+minibuffer but put point at @var{position} within the string's text.
+
+As a historical accident, @var{position} was implemented
+inconsistently in different functions.  In @code{completing-read},
+@var{position}'s value is interpreted as origin-zero; that is, a value
+of 0 means the beginning of the string, 1 means after the first
+character, etc.  In @code{read-minibuffer}, and the other
+non-completion minibuffer input functions that support this argument,
+1 means the beginning of the string 2 means after the first character,
+etc.
+
+Use of a cons cell as the value for @var{initial} arguments is
+deprecated in user code.
+
+@node Completion
+@section Completion
+@cindex completion
+
+  @dfn{Completion} is a feature that fills in the rest of a name
+starting from an abbreviation for it.  Completion works by comparing the
+user's input against a list of valid names and determining how much of
+the name is determined uniquely by what the user has typed.  For
+example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
+type the first few letters of the name of the buffer to which you wish
+to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
+extends the name as far as it can.
+
+  Standard Emacs commands offer completion for names of symbols, files,
+buffers, and processes; with the functions in this section, you can
+implement completion for other kinds of names.
+
+  The @code{try-completion} function is the basic primitive for
+completion: it returns the longest determined completion of a given
+initial string, with a given set of strings to match against.
+
+  The function @code{completing-read} provides a higher-level interface
+for completion.  A call to @code{completing-read} specifies how to
+determine the list of valid names.  The function then activates the
+minibuffer with a local keymap that binds a few keys to commands useful
+for completion.  Other functions provide convenient simple interfaces
+for reading certain kinds of names with completion.
+
+@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
+                             (reading buffer name, file name, etc.)
+* Reading File Names::     Using completion to read file names.
+* 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.
+
+@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).
+
+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.
+
+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.
+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
+think of such lists as alists.
+
+@cindex obarray in completion
+If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
+of all symbols in the obarray form the set of permissible completions.  The
+global variable @code{obarray} holds an obarray containing the names of
+all interned Lisp symbols.
+
+Note that the only valid way to make a new obarray is to create it
+empty and then add symbols to it one by one using @code{intern}.
+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.
+
+You can also use a symbol that is 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}
+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
+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
+which case it should be a function of two arguments.  It is used to
+test each possible match, and the match is accepted only if
+@var{predicate} returns non-@code{nil}.  The argument given to
+@var{predicate} is either a string or a cons cell (the @sc{car} of
+which is a string) from the alist, or a symbol (@emph{not} a symbol
+name) from the obarray.  If @var{collection} is a hash table,
+@var{predicate} is called with two arguments, the string key and the
+associated value.
+
+In addition, to be acceptable, a completion must also match all the
+regular expressions in @code{completion-regexp-list}.  (Unless
+@var{collection} is a function, in which case that function has to
+handle @code{completion-regexp-list} itself.)
+
+In the first of the following examples, the string @samp{foo} is
+matched by three of the alist @sc{car}s.  All of the matches begin with
+the characters @samp{fooba}, so that is the result.  In the second
+example, there is only one possible match, and it is exact, so the value
+is @code{t}.
+
+@smallexample
+@group
+(try-completion
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
+     @result{} "fooba"
+@end group
+
+@group
+(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
+     @result{} t
+@end group
+@end smallexample
+
+In the following example, numerous symbols begin with the characters
+@samp{forw}, and all of them begin with the word @samp{forward}.  In
+most of the symbols, this is followed with a @samp{-}, but not in all,
+so no more than @samp{forward} can be completed.
+
+@smallexample
+@group
+(try-completion "forw" obarray)
+     @result{} "forward"
+@end group
+@end smallexample
+
+Finally, in the following example, only two of the three possible
+matches pass the predicate @code{test} (the string @samp{foobaz} is
+too short).  Both of those begin with the string @samp{foobar}.
+
+@smallexample
+@group
+(defun test (s)
+  (> (length (car s)) 6))
+     @result{} test
+@end group
+@group
+(try-completion
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ 'test)
+     @result{} "foobar"
+@end group
+@end smallexample
+@end defun
+
+@defun all-completions string collection &optional predicate nospace
+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
+@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.
+
+If @var{collection} is a function, it is called with three arguments:
+@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
+returns whatever the function returns.  @xref{Programmed Completion}.
+
+Here is an example, using the function @code{test} shown in the
+example for @code{try-completion}:
+
+@smallexample
+@group
+(defun test (s)
+  (> (length (car s)) 6))
+     @result{} test
+@end group
+
+@group
+(all-completions
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ 'test)
+     @result{} ("foobar1" "foobar2")
+@end group
+@end smallexample
+@end defun
+
+@defun test-completion string collection &optional predicate
+@anchor{Definition of test-completion}
+This function returns non-@code{nil} if @var{string} is a valid
+completion possibility specified by @var{collection} and
+@var{predicate}.  The arguments are the same as in
+@code{try-completion}.  For instance, if @var{collection} is a list of
+strings, this is true if @var{string} appears in the list and
+@var{predicate} is satisfied.
+
+This function uses @code{completion-regexp-list} in the same
+way that @code{try-completion} does.
+
+If @var{predicate} is non-@code{nil} and if @var{collection} contains
+several strings that are equal to each other, as determined by
+@code{compare-strings} according to @code{completion-ignore-case},
+then @var{predicate} should accept either all or none of them.
+Otherwise, the return value of @code{test-completion} is essentially
+unpredictable.
+
+If @var{collection} is a function, it is called with three arguments,
+the values @var{string}, @var{predicate} and @code{lambda}; whatever
+it returns, @code{test-completion} returns in turn.
+@end defun
+
+@defvar completion-ignore-case
+If the value of this variable is non-@code{nil}, Emacs does not
+consider case significant in completion.
+@end defvar
+
+@defvar completion-regexp-list
+This is a list of regular expressions.  The completion functions only
+consider a completion acceptable if it matches all regular expressions
+in this list, with @code{case-fold-search} (@pxref{Searching and Case})
+bound to the value of @code{completion-ignore-case}.
+@end defvar
+
+@defmac lazy-completion-table var fun
+This macro provides a way to initialize the variable @var{var} as a
+collection for completion in a lazy way, not computing its actual
+contents until they are first needed.  You use this macro to produce a
+value that you store in @var{var}.  The actual computation of the
+proper value is done the first time you do completion using @var{var}.
+It is done by calling @var{fun} with no arguments.  The
+value @var{fun} returns becomes the permanent value of @var{var}.
+
+Here is an example of use:
+
+@smallexample
+(defvar foo (lazy-completion-table foo make-my-alist))
+@end smallexample
+@end defmac
+
+@node Minibuffer Completion
+@subsection Completion and the Minibuffer
+@cindex minibuffer completion
+@cindex reading from minibuffer with completion
+
+  This section describes the basic interface for reading from the
+minibuffer with completion.
+
+@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
+This function reads a string in the minibuffer, assisting the user by
+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{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 neither
+@code{nil} nor @code{t}, then the exit commands won't exit unless the
+input already in the buffer matches an element of @var{collection}.
+
+However, empty input is always permitted, regardless of the value of
+@var{require-match}; in that case, @code{completing-read} returns
+@var{default}, or @code{""}, if @var{default} is @code{nil}.  The
+value of @var{default} (if non-@code{nil}) is also available to the
+user through the history commands.
+
+The function @code{completing-read} uses
+@code{minibuffer-local-completion-map} as the keymap if
+@var{require-match} is @code{nil}, and uses
+@code{minibuffer-local-must-match-map} if @var{require-match} is
+non-@code{nil}.  @xref{Completion Commands}.
+
+The argument @var{hist} specifies which history list variable to use for
+saving the input and for minibuffer history commands.  It defaults to
+@code{minibuffer-history}.  @xref{Minibuffer History}.
+
+The argument @var{initial} is mostly deprecated; we recommend using a
+non-@code{nil} value only in conjunction with specifying a cons cell
+for @var{hist}.  @xref{Initial Input}.  For default input, use
+@var{default} instead.
+
+If the argument @var{inherit-input-method} is non-@code{nil}, then the
+minibuffer inherits the current input method (@pxref{Input
+Methods}) and the setting of @code{enable-multibyte-characters}
+(@pxref{Text Representations}) from whichever buffer was current before
+entering the minibuffer.
+
+If the built-in variable @code{completion-ignore-case} is
+non-@code{nil}, completion ignores case when comparing the input
+against the possible matches.  @xref{Basic Completion}.  In this mode
+of operation, @var{predicate} must also ignore case, or you will get
+surprising results.
+
+Here's an example of using @code{completing-read}:
+
+@smallexample
+@group
+(completing-read
+ "Complete a foo: "
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ nil t "fo")
+@end group
+
+@group
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following appears in the minibuffer:}
+
+---------- Buffer: Minibuffer ----------
+Complete a foo: fo@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
+@code{completing-read} returns @code{barfoo}.
+
+The @code{completing-read} function binds variables to pass
+information to the commands that actually do completion.
+They are described in the following section.
+@end defun
+
+@node Completion Commands
+@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.
+
+@defvar minibuffer-completion-table
+The value of this variable is the collection used for completion in
+the minibuffer.  This is the global variable that contains what
+@code{completing-read} passes to @code{try-completion}.  It is used by
+minibuffer completion commands such as @code{minibuffer-complete-word}.
+@end defvar
+
+@defvar minibuffer-completion-predicate
+This variable's value is the predicate that @code{completing-read}
+passes to @code{try-completion}.  The variable is also used by the other
+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.
+@end defvar
+
+@deffn Command minibuffer-complete-word
+This function completes the minibuffer contents by at most a single
+word.  Even if the minibuffer contents have only one completion,
+@code{minibuffer-complete-word} does not add any characters beyond the
+first character that is not a word constituent.  @xref{Syntax Tables}.
+@end deffn
+
+@deffn Command minibuffer-complete
+This function completes the minibuffer contents as far as possible.
+@end deffn
+
+@deffn Command minibuffer-complete-and-exit
+This function completes the minibuffer contents, and exits if
+confirmation is not required, i.e., if
+@code{minibuffer-completion-confirm} is @code{nil}.  If confirmation
+@emph{is} required, it is given by repeating this command
+immediately---the command is programmed to work without confirmation
+when run twice in succession.
+@end deffn
+
+@deffn Command minibuffer-completion-help
+This function creates a list of the possible completions of the
+current minibuffer contents.  It works by calling @code{all-completions}
+using the value of the variable @code{minibuffer-completion-table} as
+the @var{collection} argument, and the value of
+@code{minibuffer-completion-predicate} as the @var{predicate} argument.
+The list of completions is displayed as text in a buffer named
+@samp{*Completions*}.
+@end deffn
+
+@defun display-completion-list completions &optional common-substring
+This function displays @var{completions} to the stream in
+@code{standard-output}, usually a buffer.  (@xref{Read and Print}, for more
+information about streams.)  The argument @var{completions} is normally
+a list of completions just returned by @code{all-completions}, but it
+does not have to be.  Each element may be a symbol or a string, either
+of which is simply printed.  It can also be a list of two strings,
+which is printed as if the strings were concatenated.  The first of
+the two strings is the actual completion, the second string serves as
+annotation.
+
+The argument @var{common-substring} is the prefix that is common to
+all the completions.  With normal Emacs completion, it is usually the
+same as the string that was completed.  @code{display-completion-list}
+uses this to highlight text in the completion list for better visual
+feedback.  This is not needed in the minibuffer; for minibuffer
+completion, you can pass @code{nil}.
+
+This function is called by @code{minibuffer-completion-help}.  The
+most common way to use it is together with
+@code{with-output-to-temp-buffer}, like this:
+
+@example
+(with-output-to-temp-buffer "*Completions*"
+  (display-completion-list
+    (all-completions (buffer-string) my-alist)
+    (buffer-string)))
+@end example
+@end defun
+
+@defopt completion-auto-help
+If this variable is non-@code{nil}, the completion commands
+automatically display a list of possible completions whenever nothing
+can be completed because the next character is not uniquely determined.
+@end defopt
+
+@defvar minibuffer-local-completion-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is not required.  By default, this
+keymap makes the following bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}
+(@pxref{Definition of minibuffer-local-map}).
+@end defvar
+
+@defvar minibuffer-local-must-match-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is required.  Therefore, no keys
+are bound to @code{exit-minibuffer}, the command that exits the
+minibuffer unconditionally.  By default, this keymap makes the following
+bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+
+@item @kbd{C-j}
+@code{minibuffer-complete-and-exit}
+
+@item @key{RET}
+@code{minibuffer-complete-and-exit}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}.
+@end defvar
+
+@defvar minibuffer-local-filename-completion-map
+This is like @code{minibuffer-local-completion-map}
+except that it does not bind @key{SPC}.  This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
+@defvar minibuffer-local-must-match-filename-map
+This is like @code{minibuffer-local-must-match-map}
+except that it does not bind @key{SPC}.  This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
+@node High-Level Completion
+@subsection High-Level Completion  Functions
+
+  This section describes the higher-level convenient functions for
+reading certain sorts of names with completion.
+
+  In most cases, you should not call these functions in the middle of a
+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
+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},
+it should be a string or a buffer.  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 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.)
+
+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
+@samp{minibuffer.texi}, so that name is the value.
+
+@example
+(read-buffer "Buffer name: " "foo" t)
+@group
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Buffer name (default foo): @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+
+@group
+;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
+     @result{} "minibuffer.texi"
+@end group
+@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
+
+@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
+@code{read-from-minibuffer}.  Recall that a command is anything for
+which @code{commandp} returns @code{t}, and a command name is a symbol
+for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
+
+The argument @var{default} specifies what to return if the user enters
+null input.  It can be a symbol or a string; if it is a string,
+@code{read-command} interns it before returning it.  If @var{default} is
+@code{nil}, that means no default has been specified; then if the user
+enters null input, the return value is @code{(intern "")}, that is, a
+symbol whose name is an empty string.
+
+@example
+(read-command "Command name? ")
+
+@group
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Command name?
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+If the user types @kbd{forward-c @key{RET}}, then this function returns
+@code{forward-char}.
+
+The @code{read-command} function is a simplified interface to
+@code{completing-read}.  It uses the variable @code{obarray} so as to
+complete in the set of extant Lisp symbols, and it uses the
+@code{commandp} predicate so as to accept only command names:
+
+@cindex @code{commandp} example
+@example
+@group
+(read-command @var{prompt})
+@equiv{}
+(intern (completing-read @var{prompt} obarray
+                         'commandp t nil))
+@end group
+@end example
+@end defun
+
+@defun read-variable prompt &optional default
+@anchor{Definition of read-variable}
+This function reads the name of a user variable and returns it as a
+symbol.
+
+The argument @var{default} specifies what to return if the user enters
+null input.  It can be a symbol or a string; if it is a string,
+@code{read-variable} interns it before returning it.  If @var{default}
+is @code{nil}, that means no default has been specified; then if the
+user enters null input, the return value is @code{(intern "")}.
+
+@example
+@group
+(read-variable "Variable name? ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Variable name? @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
+returns @code{fill-prefix}.
+
+In general, @code{read-variable} is similar to @code{read-command},
+but uses the predicate @code{user-variable-p} instead of
+@code{commandp}:
+
+@cindex @code{user-variable-p} example
+@example
+@group
+(read-variable @var{prompt})
+@equiv{}
+(intern
+ (completing-read @var{prompt} obarray
+                  'user-variable-p t nil))
+@end group
+@end example
+@end defun
+
+  See also the functions @code{read-coding-system} and
+@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
+and @code{read-input-method-name}, in @ref{Input Methods}.
+
+@node Reading File Names
+@subsection Reading File Names
+@cindex read file names
+@cindex prompt for file name
+
+  Here is another high-level completion function, designed for reading a
+file name.  It provides 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-must-match-filename-map} if @var{existing} 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
+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
+@var{initial} is @code{nil}---don't insert any file name.  To see what
+@var{initial} does, try the command @kbd{C-x C-v}.  @strong{Please
+note:} we recommend using @var{default} rather than @var{initial} in
+most cases.
+
+If @var{default} is non-@code{nil}, then the function returns
+@var{default} if the user exits the minibuffer with the same non-empty
+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
+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
+@var{default}.  @var{default} is also available through the history
+commands.
+
+If @var{default} is @code{nil}, @code{read-file-name} tries to find a
+substitute default to use in its place, which it treats in exactly the
+same way as if it had been specified explicitly.  If @var{default} is
+@code{nil}, but @var{initial} is non-@code{nil}, then the default is
+the absolute file name obtained from @var{directory} and
+@var{initial}.  If both @var{default} and @var{initial} are @code{nil}
+and the buffer is visiting a file, @code{read-file-name} uses the
+absolute file name of that file as default.  If the buffer is not
+visiting a file, then there is no default.  In that case, if the user
+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}.
+
+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:
+
+@example
+@group
+(read-file-name "The file is ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following appears in the minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is /gp/gnu/elisp/@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+Typing @kbd{manual @key{TAB}} results in the following:
+
+@example
+@group
+---------- Buffer: Minibuffer ----------
+The file is /gp/gnu/elisp/manual.texi@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@c Wordy to avoid overfull hbox in smallbook mode.
+@noindent
+If the user types @key{RET}, @code{read-file-name} returns the file name
+as the string @code{"/gp/gnu/elisp/manual.texi"}.
+@end defun
+
+@defvar read-file-name-function
+If non-@code{nil}, this should be a function that accepts the same
+arguments as @code{read-file-name}.  When @code{read-file-name} is
+called, it calls this function with the supplied arguments instead of
+doing its usual work.
+@end defvar
+
+@defvar read-file-name-completion-ignore-case
+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
+This function is like @code{read-file-name} but allows only directory
+names as completion possibilities.
+
+If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
+@code{read-directory-name} constructs a substitute default by
+combining @var{directory} (or the current buffer's default directory
+if @var{directory} is @code{nil}) and @var{initial}.  If both
+@var{default} and @var{initial} are @code{nil}, this function uses
+@var{directory} as substitute default, or the current buffer's default
+directory if @var{directory} is @code{nil}.
+@end defun
+
+@defopt insert-default-directory
+This variable is used by @code{read-file-name}, and thus, indirectly,
+by most commands reading file names.  (This includes all commands that
+use the code letters @samp{f} or @samp{F} in their interactive form.
+@xref{Interactive Codes,, Code Characters for interactive}.)  Its
+value controls whether @code{read-file-name} starts by placing the
+name of the default directory in the minibuffer, plus the initial file
+name if any.  If the value of this variable is @code{nil}, then
+@code{read-file-name} does not place any initial input in the
+minibuffer (unless you specify initial input with the @var{initial}
+argument).  In that case, the default directory is still used for
+completion of relative file names, but is not displayed.
+
+If this variable is @code{nil} and the initial minibuffer contents are
+empty, the user may have to explicitly fetch the next history element
+to access a default value.  If the variable is non-@code{nil}, the
+initial minibuffer contents are always non-empty and the user can
+always request a default value by immediately typing @key{RET} in an
+unedited minibuffer.  (See above.)
+
+For example:
+
+@example
+@group
+;; @r{Here the minibuffer starts out with the default directory.}
+(let ((insert-default-directory t))
+  (read-file-name "The file is "))
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is ~lewis/manual/@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+
+@group
+;; @r{Here the minibuffer is empty and only the prompt}
+;;   @r{appears on its line.}
+(let ((insert-default-directory nil))
+  (read-file-name "The file is "))
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+@end defopt
+
+@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}.
+
+  To use this feature, pass a symbol with a function definition as the
+@var{collection} argument to @code{completing-read}.  The function
+@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.
+
+  The completion function should accept three arguments:
+
+@itemize @bullet
+@item
+The string to be completed.
+
+@item
+The predicate function to filter possible matches, or @code{nil} if
+none.  Your function should call the predicate for each possible match,
+and ignore the possible match if the predicate returns @code{nil}.
+
+@item
+A flag specifying the type of operation.
+@end itemize
+
+  There are three flag values for three operations:
+
+@itemize @bullet
+@item
+@code{nil} specifies @code{try-completion}.  The completion function
+should return the completion of the specified string, or @code{t} if the
+string is a unique and exact match already, or @code{nil} if the string
+matches no possibility.
+
+If the string is an exact match for one possibility, but also matches
+other longer possibilities, the function should return the string, not
+@code{t}.
+
+@item
+@code{t} specifies @code{all-completions}.  The completion function
+should return a list of all possible completions of the specified
+string.
+
+@item
+@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}.
+
+@defmac dynamic-completion-table function
+This macro is a convenient way to write a function that can act as
+programmed completion function.  The argument @var{function} should be
+a function that takes one argument, a string, and returns an alist of
+possible completions of it.  You can think of
+@code{dynamic-completion-table} as a transducer between that interface
+and the interface for programmed completion functions.
+@end defmac
+
+@node Yes-or-No Queries
+@section Yes-or-No Queries
+@cindex asking the user questions
+@cindex querying the user
+@cindex yes-or-no questions
+
+  This section describes functions used to ask the user a yes-or-no
+question.  The function @code{y-or-n-p} can be answered with a single
+character; it is useful for questions where an inadvertent wrong answer
+will not have serious consequences.  @code{yes-or-no-p} is suitable for
+more momentous questions, since it requires three or four characters to
+answer.
+
+   If either of these functions is called in a command that was invoked
+using the mouse---more precisely, if @code{last-nonmenu-event}
+(@pxref{Command Loop Info}) is either @code{nil} or a list---then it
+uses a dialog box or pop-up menu to ask the question.  Otherwise, it
+uses keyboard input.  You can force use of the mouse or use of keyboard
+input by binding @code{last-nonmenu-event} to a suitable value around
+the call.
+
+  Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
+@code{y-or-n-p} does not; but it seems best to describe them together.
+
+@defun y-or-n-p prompt
+This function asks the user a question, expecting input in the echo
+area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
+user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
+and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit,'' like
+@kbd{C-g}, because the question might look like a minibuffer and for
+that reason the user might try to use @kbd{C-]} to get out.  The answer
+is a single character, with no @key{RET} needed to terminate it.  Upper
+and lower case are equivalent.
+
+``Asking the question'' means printing @var{prompt} in the echo area,
+followed by the string @w{@samp{(y or n) }}.  If the input is not one of
+the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
+@kbd{@key{DEL}}, or something that quits), the function responds
+@samp{Please answer y or n.}, and repeats the request.
+
+This function does not actually use the minibuffer, since it does not
+allow editing of the answer.  It actually uses the echo area (@pxref{The
+Echo Area}), which uses the same screen space as the minibuffer.  The
+cursor moves to the echo area while the question is being asked.
+
+The answers and their meanings, even @samp{y} and @samp{n}, are not
+hardwired.  The keymap @code{query-replace-map} specifies them.
+@xref{Search and Replace}.
+
+In the following example, the user first types @kbd{q}, which is
+invalid.  At the next prompt the user types @kbd{y}.
+
+@smallexample
+@group
+(y-or-n-p "Do you need a lift? ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears in the echo area:}
+@end group
+
+@group
+---------- Echo area ----------
+Do you need a lift? (y or n)
+---------- Echo area ----------
+@end group
+
+;; @r{If the user then types @kbd{q}, the following appears:}
+
+@group
+---------- Echo area ----------
+Please answer y or n.  Do you need a lift? (y or n)
+---------- Echo area ----------
+@end group
+
+;; @r{When the user types a valid answer,}
+;;   @r{it is displayed after the question:}
+
+@group
+---------- Echo area ----------
+Do you need a lift? (y or n) y
+---------- Echo area ----------
+@end group
+@end smallexample
+
+@noindent
+We show successive lines of echo area messages, but only one actually
+appears on the screen at a time.
+@end defun
+
+@defun y-or-n-p-with-timeout prompt seconds default-value
+Like @code{y-or-n-p}, except that if the user fails to answer within
+@var{seconds} seconds, this function stops waiting and returns
+@var{default-value}.  It works by setting up a timer; see @ref{Timers}.
+The argument @var{seconds} may be an integer or a floating point number.
+@end defun
+
+@defun yes-or-no-p prompt
+This function asks the user a question, expecting input in the
+minibuffer.  It returns @code{t} if the user enters @samp{yes},
+@code{nil} if the user types @samp{no}.  The user must type @key{RET} to
+finalize the response.  Upper and lower case are equivalent.
+
+@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
+followed by @w{@samp{(yes or no) }}.  The user must type one of the
+expected responses; otherwise, the function responds @samp{Please answer
+yes or no.}, waits about two seconds and repeats the request.
+
+@code{yes-or-no-p} requires more work from the user than
+@code{y-or-n-p} and is appropriate for more crucial decisions.
+
+Here is an example:
+
+@smallexample
+@group
+(yes-or-no-p "Do you really want to remove everything? ")
+
+;; @r{After evaluation of the preceding expression,}
+;;   @r{the following prompt appears,}
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: minibuffer ----------
+Do you really want to remove everything? (yes or no)
+---------- Buffer: minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+If the user first types @kbd{y @key{RET}}, which is invalid because this
+function demands the entire word @samp{yes}, it responds by displaying
+these prompts, with a brief pause between them:
+
+@smallexample
+@group
+---------- Buffer: minibuffer ----------
+Please answer yes or no.
+Do you really want to remove everything? (yes or no)
+---------- Buffer: minibuffer ----------
+@end group
+@end smallexample
+@end defun
+
+@node Multiple Queries
+@section Asking Multiple Y-or-N 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
+asking each question individually.  This gives the user certain
+convenient facilities such as the ability to answer the whole series at
+once.
+
+@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
+This function asks the user a series of questions, reading a
+single-character answer in the echo area for each one.
+
+The value of @var{list} specifies the objects to ask questions about.
+It should be either a list of objects or a generator function.  If it is
+a function, it should expect no arguments, and should return either the
+next object to ask about, or @code{nil} meaning stop asking questions.
+
+The argument @var{prompter} specifies how to ask each question.  If
+@var{prompter} is a string, the question text is computed like this:
+
+@example
+(format @var{prompter} @var{object})
+@end example
+
+@noindent
+where @var{object} is the next object to ask about (as obtained from
+@var{list}).
+
+If not a string, @var{prompter} should be a function of one argument
+(the next object to ask about) and should return the question text.  If
+the value is a string, that is the question to ask the user.  The
+function can also return @code{t} meaning do act on this object (and
+don't ask the user), or @code{nil} meaning ignore this object (and don't
+ask the user).
+
+The argument @var{actor} says how to act on the answers that the user
+gives.  It should be a function of one argument, and it is called with
+each object that the user says yes for.  Its argument is always an
+object obtained from @var{list}.
+
+If the argument @var{help} is given, it should be a list of this form:
+
+@example
+(@var{singular} @var{plural} @var{action})
+@end example
+
+@noindent
+where @var{singular} is a string containing a singular noun that
+describes the objects conceptually being acted on, @var{plural} is the
+corresponding plural noun, and @var{action} is a transitive verb
+describing what @var{actor} does.
+
+If you don't specify @var{help}, the default is @code{("object"
+"objects" "act on")}.
+
+Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
+@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
+that object; @kbd{!} to act on all following objects; @key{ESC} or
+@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
+the current object and then exit; or @kbd{C-h} to get help.  These are
+the same answers that @code{query-replace} accepts.  The keymap
+@code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
+as well as for @code{query-replace}; see @ref{Search and Replace}.
+
+You can use @var{action-alist} to specify additional possible answers
+and what they mean.  It is an alist of elements of the form
+@code{(@var{char} @var{function} @var{help})}, each of which defines one
+additional answer.  In this element, @var{char} is a character (the
+answer); @var{function} is a function of one argument (an object from
+@var{list}); @var{help} is a string.
+
+When the user responds with @var{char}, @code{map-y-or-n-p} calls
+@var{function}.  If it returns non-@code{nil}, the object is considered
+``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
+@var{list}.  If it returns @code{nil}, the prompt is repeated for the
+same object.
+
+Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
+prompting.  But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
+does not do that.
+
+If @code{map-y-or-n-p} is called in a command that was invoked using the
+mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
+Loop Info}) is either @code{nil} or a list---then it uses a dialog box
+or pop-up menu to ask the question.  In this case, it does not use
+keyboard input or the echo area.  You can force use of the mouse or use
+of keyboard input by binding @code{last-nonmenu-event} to a suitable
+value around the call.
+
+The return value of @code{map-y-or-n-p} is the number of objects acted on.
+@end defun
+
+@node Reading a Password
+@section Reading a Password
+@cindex passwords, reading
+
+  To read a password to pass to another program, you can use the
+function @code{read-passwd}.
+
+@defun read-passwd prompt &optional confirm default
+This function reads a password, prompting with @var{prompt}.  It does
+not echo the password as the user types it; instead, it echoes @samp{.}
+for each character in the password.
+
+The optional argument @var{confirm}, if non-@code{nil}, says to read the
+password twice and insist it must be the same both times.  If it isn't
+the same, the user has to type it over and over until the last two
+times match.
+
+The optional argument @var{default} specifies the default password to
+return if the user enters empty input.  If @var{default} is @code{nil},
+then @code{read-passwd} returns the null string in that case.
+@end defun
+
+@node Minibuffer Commands
+@section Minibuffer Commands
+
+  This section describes some commands meant for use in the
+minibuffer.
+
+@deffn Command exit-minibuffer
+This command exits the active minibuffer.  It is normally bound to
+keys in minibuffer local keymaps.
+@end deffn
+
+@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};
+@pxref{Command Loop Info}).
+@end deffn
+
+@deffn Command previous-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element.
+@end deffn
+
+@deffn Command next-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th more recent history element.
+@end deffn
+
+@deffn Command previous-matching-history-element pattern n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element that matches @var{pattern} (a
+regular expression).
+@end deffn
+
+@deffn Command next-matching-history-element pattern n
+This command replaces the minibuffer contents with the value of the
+@var{n}th next (newer) history element that matches @var{pattern} (a
+regular expression).
+@end deffn
+
+@node Minibuffer Windows
+@section Minibuffer Windows
+@cindex minibuffer windows
+
+  These functions access and select minibuffer windows
+and test whether they are active.
+
+@defun active-minibuffer-window
+This function returns the currently active minibuffer window, or
+@code{nil} if none is currently active.
+@end defun
+
+@defun minibuffer-window &optional frame
+@anchor{Definition of minibuffer-window}
+This function returns the minibuffer window used for frame @var{frame}.
+If @var{frame} is @code{nil}, that stands for the current frame.  Note
+that the minibuffer window used by a frame need not be part of that
+frame---a frame that has no minibuffer of its own necessarily uses some
+other frame's minibuffer window.
+@end defun
+
+@defun set-minibuffer-window window
+This function specifies @var{window} as the minibuffer window to use.
+This affects where the minibuffer is displayed if you put text in it
+without invoking the usual minibuffer commands.  It has no effect on
+the usual minibuffer input functions because they all start by
+choosing the minibuffer window according to the current frame.
+@end defun
+
+@c Emacs 19 feature
+@defun window-minibuffer-p &optional window
+This function returns non-@code{nil} if @var{window} is a minibuffer
+window.
+@var{window} defaults to the selected window.
+@end defun
+
+It is not correct to determine whether a given window is a minibuffer by
+comparing it with the result of @code{(minibuffer-window)}, because
+there can be more than one minibuffer window if there is more than one
+frame.
+
+@defun minibuffer-window-active-p window
+This function returns non-@code{nil} if @var{window}, assumed to be
+a minibuffer window, is currently active.
+@end defun
+
+@node Minibuffer Contents
+@section Minibuffer Contents
+
+  These functions access the minibuffer prompt and contents.
+
+@defun minibuffer-prompt
+This function returns the prompt string of the currently active
+minibuffer.  If no minibuffer is active, it returns @code{nil}.
+@end defun
+
+@defun minibuffer-prompt-end
+This function returns the current
+position of the end of the minibuffer prompt, if a minibuffer is
+current.  Otherwise, it returns the minimum valid buffer position.
+@end defun
+
+@defun minibuffer-prompt-width
+This function returns the current display-width of the minibuffer
+prompt, if a minibuffer is current.  Otherwise, it returns zero.
+@end defun
+
+@defun minibuffer-contents
+This function returns the editable
+contents of the minibuffer (that is, everything except the prompt) as
+a string, if a minibuffer is current.  Otherwise, it returns the
+entire contents of the current buffer.
+@end defun
+
+@defun minibuffer-contents-no-properties
+This is like @code{minibuffer-contents}, except that it does not copy text
+properties, just the characters themselves.  @xref{Text Properties}.
+@end defun
+
+@defun minibuffer-completion-contents
+This is like @code{minibuffer-contents}, except that it returns only
+the contents before point.  That is the part that completion commands
+operate on.  @xref{Minibuffer Completion}.
+@end defun
+
+@defun delete-minibuffer-contents
+This function erases the editable contents of the minibuffer (that is,
+everything except the prompt), if a minibuffer is current.  Otherwise,
+it erases the entire current buffer.
+@end defun
+
+@node Recursive Mini
+@section Recursive Minibuffers
+@cindex recursive minibuffers
+
+  These functions and variables deal with recursive minibuffers
+(@pxref{Recursive Editing}):
+
+@defun minibuffer-depth
+This function returns the current depth of activations of the
+minibuffer, a nonnegative integer.  If no minibuffers are active, it
+returns zero.
+@end defun
+
+@defopt enable-recursive-minibuffers
+If this variable is non-@code{nil}, you can invoke commands (such as
+@code{find-file}) that use minibuffers even while the minibuffer window
+is active.  Such invocation produces a recursive editing level for a new
+minibuffer.  The outer-level minibuffer is invisible while you are
+editing the inner one.
+
+If this variable is @code{nil}, you cannot invoke minibuffer
+commands when the minibuffer window is active, not even if you switch to
+another window to do it.
+@end defopt
+
+@c Emacs 19 feature
+If a command name has a property @code{enable-recursive-minibuffers}
+that is non-@code{nil}, then the command can use the minibuffer to read
+arguments even if it is invoked from the minibuffer.  A command can
+also achieve this by binding @code{enable-recursive-minibuffers}
+to @code{t} in the interactive declaration (@pxref{Using Interactive}).
+The minibuffer command @code{next-matching-history-element} (normally
+@kbd{M-s} in the minibuffer) does the latter.
+
+@node Minibuffer Misc
+@section Minibuffer Miscellany
+
+@defun minibufferp &optional buffer-or-name
+This function returns non-@code{nil} if @var{buffer-or-name} is a
+minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
+buffer.
+@end defun
+
+@defvar minibuffer-setup-hook
+This is a normal hook that is run whenever the minibuffer is entered.
+@xref{Hooks}.
+@end defvar
+
+@defvar minibuffer-exit-hook
+This is a normal hook that is run whenever the minibuffer is exited.
+@xref{Hooks}.
+@end defvar
+
+@defvar minibuffer-help-form
+@anchor{Definition of minibuffer-help-form}
+The current value of this variable is used to rebind @code{help-form}
+locally inside the minibuffer (@pxref{Help Functions}).
+@end defvar
+
+@defvar minibuffer-scroll-window
+@anchor{Definition of minibuffer-scroll-window}
+If the value of this variable is non-@code{nil}, it should be a window
+object.  When the function @code{scroll-other-window} is called in the
+minibuffer, it scrolls this window.
+@end defvar
+
+@defun minibuffer-selected-window
+This function returns the window which was selected when the
+minibuffer was entered.  If selected window is not a minibuffer
+window, it returns @code{nil}.
+@end defun
+
+@defopt max-mini-window-height
+This variable specifies the maximum height for resizing minibuffer
+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
+
+@defun minibuffer-message string
+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.
+@end defun
+
+@ignore
+   arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
+@end ignore