@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Minibuffer, M-x, Basic, Top
+@node Minibuffer
@chapter The Minibuffer
@cindex minibuffer
* Minibuffer History:: Reusing recent minibuffer arguments.
* Repetition:: Re-executing commands that used the minibuffer.
* Passwords:: Entering passwords in the echo area.
+* Yes or No Prompts:: Replying yes or no in the echo area.
@end menu
@node Minibuffer File
directory}. For example, it may start out like this:
@example
-Find File: /u2/emacs/src/
+Find file: /u2/emacs/src/
@end example
@noindent
-Here, @samp{Find File:@: } is the prompt and @samp{/u2/emacs/src/} is
+Here, @samp{Find file:@: } is the prompt and @samp{/u2/emacs/src/} is
the default directory. If you now type @kbd{buffer.c} as input, that
specifies the file @file{/u2/emacs/src/buffer.c}. @xref{File Names},
for information about the default directory.
For example, you can specify @file{/etc/termcap} as follows:
@example
-Find File: /u2/emacs/src//etc/termcap
+Find file: /u2/emacs/src//etc/termcap
@end example
@noindent
@cindex slashes repeated in file name
@findex file-name-shadow-mode
Emacs interprets a double slash as ``ignore everything before the
-second slash in the pair.'' In the example above,
+second slash in the pair''. In the example above,
@file{/u2/emacs/src/} is ignored, so the argument you supplied is
@file{/etc/termcap}. The ignored part of the file name is dimmed if
the terminal allows it. (To disable this dimming, turn off File Name
the minibuffer is active. To allow such commands in the minibuffer,
set the variable @code{enable-recursive-minibuffers} to @code{t}.
+@findex minibuffer-inactive-mode
+ When not active, the minibuffer is in @code{minibuffer-inactive-mode},
+and clicking @kbd{Mouse-1} there shows the @file{*Messages*} buffer.
+If you use a dedicated frame for minibuffers, Emacs also recognizes
+certain keys there, for example @kbd{n} to make a new frame.
+
@node Completion
@section Completion
@c This node is referenced in the tutorial. When renaming or deleting
Completion}.
@menu
-* Example: Completion Example. Examples of using completion.
-* Commands: Completion Commands. A list of completion commands.
-* Strict Completion:: Different types of completion.
-* Completion Styles:: How completion matches are chosen.
-* Options: Completion Options. Options for completion.
+* Completion Example:: Examples of using completion.
+* Completion Commands:: A list of completion commands.
+* Completion Exit:: Completion and minibuffer text submission.
+* Completion Styles:: How completion matches are chosen.
+* Completion Options:: Options for completion.
@end menu
@node Completion Example
completion alternatives (in this case, command names) that start with
@samp{au}. There are several, including @code{auto-fill-mode} and
@code{autoconf-mode}, but they all begin with @code{auto}, so the
-@samp{au} in the minibuffer completes to @samp{auto}.
+@samp{au} in the minibuffer completes to @samp{auto}. (More commands
+may be defined in your Emacs session. For example, if a command
+called @code{authorize-me} was defined, Emacs could only complete
+as far as @samp{aut}.)
If you type @key{TAB} again immediately, it cannot determine the
next character; it could be @samp{-}, @samp{a}, or @samp{c}. So it
arguments that often include spaces, such as file names.
@item @key{RET}
Submit the text in the minibuffer as the argument, possibly completing
-first (@code{minibuffer-complete-and-exit}). @xref{Strict Completion}.
+first (@code{minibuffer-complete-and-exit}). @xref{Completion Exit}.
@item ?
Display a list of completions (@code{minibuffer-completion-help}).
@end table
completion alternative (@code{previous-completion}).
@end table
-@node Strict Completion
-@subsection Strict Completion
+@node Completion Exit
+@subsection Completion Exit
- There are three ways that the @key{RET}
-(@code{minibuffer-complete-and-exit}) completion command can act,
-depending on how the argument will be used.
+@kindex RET @r{(completion in minibuffer)}
+@findex minibuffer-complete-and-exit
+ When a command reads an argument using the minibuffer with
+completion, it also controls what happens when you type @key{RET}
+(@code{minibuffer-complete-and-exit}) to submit the argument. There
+are four types of behavior:
@itemize @bullet
@item
-@dfn{Strict} completion accepts only known completion candidates. For
-example, when @kbd{C-x k} reads the name of a buffer to kill, only the
-name of an existing buffer makes sense. In strict completion,
-@key{RET} refuses to exit if the text in the minibuffer does not
-complete to an exact match.
+@dfn{Strict completion} accepts only exact completion matches. Typing
+@key{RET} exits the minibuffer only if the minibuffer text is an exact
+match, or completes to one. Otherwise, Emacs refuses to exit the
+minibuffer; instead it tries to complete, and if no completion can be
+done it momentarily displays @samp{[No match]} after the minibuffer
+text. (You can still leave the minibuffer by typing @kbd{C-g} to
+cancel the command.)
+
+An example of a command that uses this behavior is @kbd{M-x}, since it
+is meaningless for it to accept a non-existent command name.
@item
-@dfn{Cautious} completion is similar to strict completion, except that
-@key{RET} exits only if the text is an already exact match.
-Otherwise, @key{RET} does not exit, but it does complete the text. If
-that completes to an exact match, a second @key{RET} will exit.
+@dfn{Cautious completion} is like strict completion, except @key{RET}
+exits only if the text is already an exact match. If the text
+completes to an exact match, @key{RET} performs that completion but
+does not exit yet; you must type a second @key{RET} to exit.
Cautious completion is used for reading file names for files that must
already exist, for example.
@item
-@dfn{Permissive} completion allows any input; the completion
-candidates are just suggestions. For example, when @kbd{C-x C-f}
-reads the name of a file to visit, any file name is allowed, including
-nonexistent file (in case you want to create a file). In permissive
-completion, @key{RET} does not complete, it just submits the argument
-as you have entered it.
-@end itemize
+@dfn{Permissive completion} allows any input; the completion
+candidates are just suggestions. Typing @key{RET} does not complete,
+it just submits the argument as you have entered it.
- Like the other completion commands, @key{RET} displays a list of all
-possible completions whenever it is supposed to complete but is unable
-to complete any further.
+@cindex minibuffer confirmation
+@cindex confirming in the minibuffer
+@item
+@dfn{Permissive completion with confirmation} is like permissive
+completion, with an exception: if you typed @key{TAB} and this
+completed the text up to some intermediate state (i.e., one that is not
+yet an exact completion match), typing @key{RET} right afterward does
+not submit the argument. Instead, Emacs asks for confirmation by
+momentarily displaying @samp{[Confirm]} after the text; type @key{RET}
+again to confirm and submit the text. This catches a common mistake,
+in which one types @key{RET} before realizing that @key{TAB} did not
+complete as far as desired.
+
+@vindex confirm-nonexistent-file-or-buffer
+You can tweak the confirmation behavior by customizing the variable
+@code{confirm-nonexistent-file-or-buffer}. The default value,
+@code{after-completion}, gives the behavior we have just described.
+If you change it to @code{nil}, Emacs does not ask for confirmation,
+falling back on permissive completion. If you change it to any other
+non-@code{nil} value, Emacs asks for confirmation whether or not the
+preceding command was @key{TAB}.
+
+This behavior is used by most commands that read file names, like
+@kbd{C-x C-f}, and commands that read buffer names, like @kbd{C-x b}.
+@end itemize
@node Completion Styles
@subsection How Completion Alternatives Are Chosen
@item emacs22
This completion style is similar to @code{basic}, except that it
ignores the text in the minibuffer after point. It is so-named
-because it corresponds to the completion behavior in Emacs 22 and
-earlier.
+because it corresponds to the completion behavior in Emacs 22.
@end table
@noindent
matches @samp{lch} to @samp{list-command-history}.
@end table
+@noindent
+There is also a very simple completion style called @code{emacs21}.
+In this style, if the text in the minibuffer is @samp{foobar},
+only matches starting with @samp{foobar} are considered.
+
+@vindex completion-category-overrides
+You can use different completion styles in different situations,
+by setting the variable @code{completion-category-overrides}.
+For example, the default setting says to use only @code{basic}
+and @code{substring} completion for buffer names.
+
+
@node Completion Options
@subsection Completion Options
@kbd{?} to display the list. If the value is @code{lazy}, Emacs only
shows the completion list buffer on the second attempt to complete.
In other words, if there is nothing to complete, the first @key{TAB}
-echoes @samp{Next char not unique}; the second @key{TAB} does the
+echoes @samp{Next char not unique}; the second @key{TAB} shows the
completion list buffer.
@vindex completion-cycle-threshold
@vindex command-history
The list of previous minibuffer-using commands is stored as a Lisp
list in the variable @code{command-history}. Each element is a Lisp
-expression which describes one command and its arguments. Lisp programs
+expression that describes one command and its arguments. Lisp programs
can re-execute a command by calling @code{eval} with the
@code{command-history} element.
@key{ESC} to submit the password. Any other self-inserting character
key inserts the associated character into the password, and all other
input is ignored.
+
+@node Yes or No Prompts
+@section Yes or No Prompts
+
+ An Emacs command may require you to answer a ``yes or no'' question
+during the course of its execution. Such queries come in two main
+varieties.
+
+@cindex y or n prompt
+ For the first type of ``yes or no'' query, the prompt ends with
+@samp{(y or n)}. Such a query does not actually use the minibuffer;
+the prompt appears in the echo area, and you answer by typing either
+@samp{y} or @samp{n}, which immediately delivers the response. For
+example, if you type @kbd{C-x C-w} (@kbd{write-file}) to save a
+buffer, and enter the name of an existing file, Emacs issues a prompt
+like this:
+
+@smallexample
+File `foo.el' exists; overwrite? (y or n)
+@end smallexample
+
+@noindent
+Because this query does not actually use the minibuffer, the usual
+minibuffer editing commands cannot be used. However, you can perform
+some window scrolling operations while the query is active: @kbd{C-l}
+recenters the selected window; @kbd{M-v} (or @key{PageDown} or
+@key{next}) scrolls forward; @kbd{C-v} (or @key{PageUp}, or
+@key{prior}) scrolls backward; @kbd{C-M-v} scrolls forward in the next
+window; and @kbd{C-M-S-v} scrolls backward in the next window. Typing
+@kbd{C-g} dismisses the query, and quits the command that issued it
+(@pxref{Quitting}).
+
+@cindex yes or no prompt
+ The second type of ``yes or no'' query is typically employed if
+giving the wrong answer would have serious consequences; it uses the
+minibuffer, and features a prompt ending with @samp{(yes or no)}. For
+example, if you invoke @kbd{C-x k} (@code{kill-buffer}) on a
+file-visiting buffer with unsaved changes, Emacs activates the
+minibuffer with a prompt like this:
+
+@smallexample
+Buffer foo.el modified; kill anyway? (yes or no)
+@end smallexample
+
+@noindent
+To answer, you must type @samp{yes} or @samp{no} into the minibuffer,
+followed by @key{RET}. The minibuffer behaves as described in the
+previous sections; you can switch to another window with @kbd{C-x o},
+use the history commands @kbd{M-p} and @kbd{M-f}, etc. Type @kbd{C-g}
+to quit the minibuffer and the querying command.
HCoop / bpt / emacs.git / blobdiff