@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
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
@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, but only while it is in use
-for reading an argument.
+ 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.
* 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
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{Minibuffer Misc}).
+name on command symbols (@pxref{Recursive Mini}).
- Like other buffers, a minibuffer may use any of several local keymaps
-(@pxref{Keymaps}); these contain various exit commands and in some cases
-completion commands (@pxref{Completion}).
-
-@itemize @bullet
-@item
-@code{minibuffer-local-map} is for ordinary input (no completion).
-
-@item
-@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
-just like @key{RET}.
-
-@item
-@code{minibuffer-local-completion-map} is for permissive completion.
-
-@item
-@code{minibuffer-local-must-match-map} is for strict completion and
-for cautious completion.
-@end itemize
+ 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
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.
+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
Representations}) from whichever buffer was current before entering the
minibuffer.
-If @var{initial-contents} is a string, @code{read-from-minibuffer}
-inserts it into the minibuffer, leaving point at the end, before the
-user starts to edit the text. The minibuffer appears with this text as
-its initial contents.
-
-Alternatively, @var{initial-contents} can 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 @emph{one-indexed}
-@var{position} in the minibuffer, rather than at the end. Any integer
-value less or equal to one puts point at the beginning of the string.
-
-@strong{Usage note:} The @var{initial-contents} argument and the
-@var{default} argument are two alternative features for more or less the
-same job. It does not make sense to use both features in a single call
-to @code{read-from-minibuffer}. In general, we recommend using
-@var{default}, since this permits the user to insert the default value
-when it is wanted, but does not burden the user with deleting it from
-the minibuffer on other occasions. For an exception to this rule,
-see @ref{Minibuffer History}.
+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
properties unconditionally, regardless of the value of this variable.
@end defvar
-@anchor{Definition of minibuffer-local-map}
@defvar minibuffer-local-map
+@anchor{Definition of minibuffer-local-map}
This is the default local keymap for reading from the minibuffer. By
default, it makes the following bindings:
@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}
inputs. It's the Lisp programmer's job to specify the right history
list for each use of the minibuffer.
- The basic minibuffer input functions @code{read-from-minibuffer} and
-@code{completing-read} both accept an optional argument named @var{hist}
-which is how you specify the history list. Here are the possible
-values:
+ 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}
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.
+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{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.
+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).
+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:
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
@node Basic Completion
@subsection Basic Completion Functions
- The 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.
+ 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, 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 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
If @var{collection} is an alist (@pxref{Association Lists}), the
permissible completions are the elements of the alist that are either
-strings or conses whose @sc{car} is a string. Other elements of the
-alist are ignored. (Remember that in Emacs Lisp, the elements of
-alists do not @emph{have} to be conses.) As all elements of the alist
-can be strings, this case actually includes lists of strings, even
-though we usually do not think of such lists as alists.
+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.) As all
+elements of the alist can be strings, this case actually includes
+lists of strings or symbols, 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
@end smallexample
@end defun
-@anchor{Definition of test-completion}
@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
bound to the value of @code{completion-ignore-case}.
@end defvar
-@defmac lazy-completion-table var fun &rest args
+@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 the arguments @var{args}. The
+It is done by calling @var{fun} with no arguments. The
value @var{fun} returns becomes the permanent value of @var{var}.
-Here are two examples of use:
+Here is an example of use:
-@example
-(defvar foo (lazy-completion-table foo make-my-alist 'global))
-
-(make-local-variable 'bar)
-(setq bar (lazy-completion-table foo make-my-alist 'local)
-@end example
+@smallexample
+(defvar foo (lazy-completion-table foo make-my-alist))
+@end smallexample
@end defmac
@node Minibuffer Completion
saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
-If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
-into the minibuffer as part of the input, with point at the end. Then
-it allows the user to edit the input, providing several commands to
-attempt completion. @var{initial} can also be a cons cell of the form
-@code{(@var{string} . @var{position})}. In that case, point is put at
-@emph{zero-indexed} position @var{position} in @var{string}. Note
-that this is different from @code{read-from-minibuffer} and related
-functions, which use a one-indexed position. In most cases, we
-recommend using @var{default}, and not @var{initial}.
-
-@strong{We discourage use of a non-@code{nil} value for
-@var{initial}}, because it is an intrusive interface. The history
-list feature (which did not exist when we introduced @var{initial})
-offers a far more convenient and general way for the user to get the
-default and edit it, and it is always available. For an exception to
-this rule, see @ref{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
(@pxref{Text Representations}) from whichever buffer was current before
entering the minibuffer.
-Completion ignores case when comparing the input against the possible
-matches, if the built-in variable @code{completion-ignore-case} is
-non-@code{nil}. @xref{Basic Completion}.
+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}:
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 three variables to pass
-information to the commands that actually do completion. These
-variables are @code{minibuffer-completion-table},
-@code{minibuffer-completion-predicate} and
-@code{minibuffer-completion-confirm}. For more information about them,
-see @ref{Completion Commands}.
+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
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.
-
-@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
+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
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,
when run twice in succession.
@end deffn
-@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. The
-function @code{minibuffer-complete-and-exit} checks the value of this
-variable before it exits.
-@end defvar
-
@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}
@samp{*Completions*}.
@end deffn
-@defun display-completion-list completions
+@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
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)))
+ (all-completions (buffer-string) my-alist)
+ (buffer-string)))
@end example
@end defun
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
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
@samp{minibuffer.texi}, so that name is the value.
@example
-(read-buffer "Buffer name? " "foo" t)
+(read-buffer "Buffer name: " "foo" t)
@group
;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,}
@group
---------- Buffer: Minibuffer ----------
-Buffer name? (default foo) @point{}
+Buffer name (default foo): @point{}
---------- Buffer: Minibuffer ----------
@end group
@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.
If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
returns @code{fill-prefix}.
-This function is similar to @code{read-command}, but uses the
-predicate @code{user-variable-p} instead of @code{commandp}:
+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
@end defun
See also the functions @code{read-coding-system} and
-@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}.
+@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
@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},
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.
@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 the
-current buffer's default directory as substitute default, ignoring
-@var{directory}.
+@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
then @code{read-passwd} returns the null string in that case.
@end defun
-@node Minibuffer Misc
-@section Minibuffer Miscellany
+@node Minibuffer Commands
+@section Minibuffer Commands
- This section describes some basic functions and variables related to
-minibuffers.
+ 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
regular expression).
@end deffn
-@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
-@tindex minibuffer-prompt-end
-This function, available starting in Emacs 21, 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-contents
-@tindex minibuffer-contents
-This function, available starting in Emacs 21, 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
-@tindex 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 delete-minibuffer-contents
-@tindex delete-minibuffer-contents
-This function, available starting in Emacs 21, erases the editable
-contents of the minibuffer (that is, everything except the prompt), if
-a minibuffer is current. Otherwise, it erases the entire buffer.
-@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
-
-@defvar minibuffer-setup-hook
-This is a normal hook that is run whenever the minibuffer is entered.
-@xref{Hooks}.
-@end defvar
+@node Minibuffer Windows
+@section Minibuffer Windows
-@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
-The current value of this variable is used to rebind @code{help-form}
-locally inside the minibuffer (@pxref{Help Functions}).
-@end defvar
-
-@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
+ 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
@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
a minibuffer window, is currently active.
@end defun
-@defvar 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
+@node Minibuffer Contents
+@section Minibuffer Contents
-@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}.
+ 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
-Finally, some functions and variables deal with recursive minibuffers
+@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
+
+ These functions and variables deal with recursive minibuffers
(@pxref{Recursive Editing}):
@defun minibuffer-depth
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