@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Minibuffer, M-x, Basic, Top
@chapter The Minibuffer
@cindex prompt
When the minibuffer is in use, it appears in the echo area, and the
terminal's cursor moves there. The beginning of the minibuffer line
-displays a @dfn{prompt} which says what kind of input you should supply and
-how it will be used. Often this prompt is derived from the name of the
-command that the argument is for. The prompt normally ends with a colon.
+displays a @dfn{prompt} in a special color, to say what kind of input
+you should supply and how it will be used. Often this prompt is
+derived from the name of the command that the argument is for. The
+prompt normally ends with a colon.
@cindex default argument
- Sometimes a @dfn{default argument} appears in parentheses after the
+ Sometimes a @dfn{default argument} appears in parentheses before the
colon; it too is part of the prompt. The default will be used as the
-argument value if you enter an empty argument (for example, just type
+argument value if you enter an empty argument (that is, just type
@key{RET}). For example, commands that read buffer names always show a
default, which is the name of the buffer that will be used if you type
just @key{RET}.
anything.
@item
-If in the minibuffer you use a command whose purpose is to print a
-message in the echo area, such as @kbd{C-x =}, the message is printed
-normally, and the minibuffer is hidden for a while. It comes back
-after a few seconds, or as soon as you type anything.
+If in the minibuffer you use a command whose purpose is to display a
+message in the echo area, such as @kbd{C-x =}, the message hides the
+minibuffer for a while. The minibuffer contents come back after a few
+seconds, or as soon as you type anything.
@item
Echoing of keystrokes does not take place while the minibuffer is in
you which directory the file will be found in if you do not specify a
directory.
-@c Separate paragraph to clean up ugly pagebreak--rms
+@c Separate paragraph to clean up ugly page break--rms
@need 1500
For example, the minibuffer might start out with these contents:
@end example
@noindent
-where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c}
-specifies the file @file{/u2/emacs/src/buffer.c}. To find files in
-nearby directories, use @kbd{..}; thus, if you type
+where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} as
+input specifies the file @file{/u2/emacs/src/buffer.c}. To find files
+in nearby directories, use @kbd{..}; thus, if you type
@kbd{../lisp/simple.el}, you will get the file named
@file{/u2/emacs/lisp/simple.el}. Alternatively, you can kill with
@kbd{M-@key{DEL}} the directory names you don't want (@pxref{Words}).
@cindex // in file name
@cindex double slash in file name
@cindex slashes repeated in file name
+@findex file-name-shadow-mode
GNU Emacs gives a special meaning to a double slash (which is not
-normally a useful thing to write): it means, ``ignore everything before
-the second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored
-in the example above, and you get the file @file{/etc/termcap}.
-
- If you set @code{insert-default-directory} to @code{nil}, the default
-directory is not inserted in the minibuffer. This way, the minibuffer
-starts out empty. But the name you type, if relative, is still
-interpreted with respect to the same default directory.
+normally a useful thing to write): it means, ``ignore everything
+before the second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is
+ignored in the example above, and you get the file
+@file{/etc/termcap}. The ignored part of the file name is dimmed if
+the terminal allows it; to disable this, turn off
+@code{file-name-shadow-mode} minor mode.
+
+ If you set @code{insert-default-directory} to @code{nil}, the
+default directory is never inserted in the minibuffer---so the
+minibuffer starts out empty. But the name you type, if relative, is
+still interpreted with respect to the same default directory.
@node Minibuffer Edit
@section Editing in the Minibuffer
Since @key{RET} in the minibuffer is defined to exit the minibuffer,
you can't use it to insert a newline in the minibuffer. To do that,
-type @kbd{C-o} or @kbd{C-q C-j}. (Recall that a newline is really the
-character control-J.)
-
- The minibuffer has its own window which always has space on the screen
-but acts as if it were not there when the minibuffer is not in use. When
-the minibuffer is in use, its window is just like the others; you can
-switch to another window with @kbd{C-x o}, edit text in other windows and
-perhaps even visit more files, before returning to the minibuffer to submit
-the argument. You can kill text in another window, return to the
-minibuffer window, and then yank the text to use it in the argument.
-@xref{Windows}.
+type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the
+@acronym{ASCII} character control-J.)
+
+ The minibuffer has its own window, which normally has space on the
+Emacs frame at all times, but it only acts like an Emacs window when
+the minibuffer is really in use. At those times, its window is much
+like any other Emacs window; you can switch from the minibuffer window
+to another window with @kbd{C-x o}, and edit text in other windows,
+before returning to the minibuffer to submit the argument. You can
+kill text in another window, return to the minibuffer window, and then
+yank the text to use it in the argument. @xref{Windows}.
@cindex height of minibuffer
@cindex size of minibuffer
@cindex growing minibuffer
@cindex resizing minibuffer
-@vindex max-mini-window-height
There are some restrictions on the use of the minibuffer window,
however. You cannot switch buffers in it---the minibuffer and its
window are permanently attached. Also, you cannot split or kill the
minibuffer window. But you can make it taller in the normal fashion
-with @kbd{C-x ^}. The minibuffer window expands vertically as necessary
-to hold the text that you put in the minibuffer. Customize the variable
-@code{max-mini-window-height} to control the maximum height for resizing
-the minibuffer window: if a floating-point number, it specifies a
-fraction of the frame's height; if an integer, it specifies the maximum
-number of lines; if nil, the minibuffer window is not resized. The
-default value is 0.25.
-
-@vindex minibuffer-scroll-overlap
- Scrolling works specially in the minibuffer window. When the
-minibuffer is just one line high, and it contains a long line of text
-that won't fit on the screen, scrolling automatically maintains an
-overlap of a certain number of characters from one continuation line to
-the next. The variable @code{minibuffer-scroll-overlap} specifies how
-many characters of overlap; the default is 20.
-
- If while in the minibuffer you issue a command that displays help text
-of any sort in another window, you can use the @kbd{C-M-v} command while
-in the minibuffer to scroll the help text. This lasts until you exit
-the minibuffer. This feature is especially useful if a completing
-minibuffer gives you a list of possible completions. @xref{Other Window}.
+with @kbd{C-x ^}.
+
+@vindex resize-mini-windows
+ The minibuffer window expands vertically as necessary to hold the
+text that you put in the minibuffer. If @code{resize-mini-windows} is
+@code{t} (the default), the window is always resized to fit the size
+of the text it displays. If its value is the symbol @code{grow-only},
+the window grows when the size of displayed text increases, but
+shrinks (back to the normal size) only when the minibuffer becomes
+inactive. If its value is @code{nil}, you have to adjust the height
+yourself.
+
+@vindex max-mini-window-height
+ The variable @code{max-mini-window-height} controls the maximum
+height for resizing the minibuffer window: a floating-point number
+specifies a fraction of the frame's height; an integer specifies the
+maximum number of lines; @code{nil} means do not resize the minibuffer
+window automatically. The default value is 0.25.
+
+ If, while in the minibuffer, you issue a command that displays help
+text of any sort in another window, you can use the @kbd{C-M-v}
+command while in the minibuffer to scroll the help text.
+(@kbd{M-@key{PAGEUP}} and @kbd{M-@key{PAGEDOWN}} also operate on that
+help text.) This lasts until you exit the minibuffer. This feature
+is especially useful when you display a buffer listing possible
+completions. @xref{Other Window}.
@vindex enable-recursive-minibuffers
Emacs normally disallows most commands that use the minibuffer while
can be determined from the part you have typed.
When completion is available, certain keys---@key{TAB}, @key{RET}, and
-@key{SPC}---are rebound to complete the text present in the minibuffer
+@key{SPC}---are rebound to complete the text in the minibuffer before point
into a longer string that it stands for, by matching it against a set of
@dfn{completion alternatives} provided by the command reading the
argument. @kbd{?} is defined to display a list of possible completions
of what you have inserted.
- For example, when @kbd{M-x} uses the minibuffer to read the name of a
-command, it provides a list of all available Emacs command names to
-complete against. The completion keys match the text in the minibuffer
+ For example, when @kbd{M-x} uses the minibuffer to read the name of
+a command, it provides a list of all available Emacs command names to
+complete against. The completion keys match the minibuffer text
against all the command names, find any additional name characters
implied by the ones already present in the minibuffer, and add those
characters to the ones you have given. This is what makes it possible
to type @kbd{M-x ins @key{SPC} b @key{RET}} instead of @kbd{M-x
-insert-buffer @key{RET}} (for example).
+insert-buffer @key{RET}} (for example). (@key{SPC} does not do
+completion in reading file names, because it is common to use spaces
+in file names on some systems.)
Case is normally significant in completion, because it is significant
in most of the names that you can complete (buffer names, file names and
Completion does ignore case distinctions for certain arguments in which
case does not matter.
+ Completion acts only on the text before point. If there is text in
+the minibuffer after point---i.e., if you move point backward after
+typing some text into the minibuffer---it remains unchanged.
+
@menu
-* Example: Completion Example.
-* Commands: Completion Commands.
-* Strict Completion::
-* Options: Completion Options.
+* Example: Completion Example. Examples of using completion.
+* Commands: Completion Commands. A list of completion commands.
+* Strict Completion:: Different types of completion.
+* Options: Completion Options. Options for completion.
@end menu
@node Completion Example
@table @kbd
@item @key{TAB}
-Complete the text in the minibuffer as much as possible
+Complete the text before point in the minibuffer as much as possible
(@code{minibuffer-complete}).
@item @key{SPC}
-Complete the minibuffer text, but don't go beyond one word
-(@code{minibuffer-complete-word}).
+Complete the minibuffer text before point, but don't go beyond one
+word (@code{minibuffer-complete-word}). @key{SPC} for completion is
+not available when entering a file name, since some users often put
+spaces in filenames.
@item @key{RET}
Submit the text in the minibuffer as the argument, possibly completing
-first as described below (@code{minibuffer-complete-and-exit}).
+first as described
+@iftex
+in the next subsection (@code{minibuffer-complete-and-exit}).
+@end iftex
+@ifnottex
+in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict
+Completion}.
+@end ifnottex
@item ?
-Print a list of all possible completions of the text in the minibuffer
-(@code{minibuffer-list-completions}).
+Display a list of all possible completions of the text in the minibuffer
+(@code{minibuffer-completion-help}).
@end table
@kindex SPC
type @key{SPC}, it finds that the completion is @samp{auto-fill-mode},
but it stops completing after @samp{fill-}. This gives
@samp{auto-fill-}. Another @key{SPC} at this point completes all the
-way to @samp{auto-fill-mode}. @key{SPC} in the minibuffer when
-completion is available runs the command
-@code{minibuffer-complete-word}.
+way to @samp{auto-fill-mode}. The command that implements this
+behavior is called @code{minibuffer-complete-word}.
Here are some commands you can use to choose a completion from a
window that displays a list of completions:
@table @kbd
@findex mouse-choose-completion
-@item Mouse-2
-Clicking mouse button 2 on a completion in the list of possible
+@item Mouse-1
+@itemx Mouse-2
+Clicking mouse button 1 or 2 on a completion in the list of possible
completions chooses that completion (@code{mouse-choose-completion}).
-You normally use this command while point is in the minibuffer; but you
+You normally use this command while point is in the minibuffer, but you
must click in the list of completions, not in the minibuffer itself.
@findex switch-to-completions
@subsection Completion Options
@vindex completion-ignored-extensions
+@cindex ignored file names, in completion
When completion is done on file names, certain file names are usually
ignored. The variable @code{completion-ignored-extensions} contains a
list of strings; a file whose name ends in any of those strings is
strings, then they are not ignored. Ignored extensions do not apply to
lists of completions---those always mention all possible completions.
+ If an element of the list in @code{completion-ignored-extensions} ends
+in a slash @file{/}, it indicates a subdirectory that should be ignored
+when completing file names. Elements of
+@code{completion-ignored-extensions} which do not end in a slash are
+never considered when a completion candidate is a directory; thus,
+completion returns directories whose names end in @file{.elc} even
+though there's an element @code{".elc"} in the list.
+
@vindex completion-auto-help
- Normally, a completion command that finds the next character is undetermined
-automatically displays a list of all possible completions. If the variable
-@code{completion-auto-help} is set to @code{nil}, this does not happen,
-and you must type @kbd{?} to display the possible completions.
+ Normally, a completion command that cannot determine even one
+additional character automatically displays a list of all possible
+completions. If the variable @code{completion-auto-help} is set to
+@code{nil}, this automatic display is disabled, so you must type
+@kbd{?} to display the list of completions.
-@pindex complete
@cindex Partial Completion mode
@vindex partial-completion-mode
@findex partial-completion-mode
+ Partial Completion mode implements a more powerful kind of
+completion that can complete multiple words in parallel. For example,
+it can complete the command name abbreviation @code{p-b} into
+@code{print-buffer}, because no other command starts with two words
+whose initials are @samp{p} and @samp{b}.
+
+ Partial completion of directories in file names uses @samp{*} to
+indicate the places for completion; thus, @file{/u*/b*/f*} might
+complete to @file{/usr/bin/foo}.
+
+ To enable this mode, use the command @kbd{M-x
+partial-completion-mode}, or customize the variable
+@code{partial-completion-mode}. This binds the partial completion
+commands to @key{TAB}, @key{SPC}, @key{RET}, and @kbd{?}. The usual
+completion commands are available on @kbd{M-@key{TAB}} (or
+@kbd{C-M-i}), @kbd{M-@key{SPC}}, @kbd{M-@key{RET}} and @kbd{M-?}.
+
@vindex PC-include-file-path
@vindex PC-disable-includes
- The @code{complete} library implements a more powerful kind of
-completion that can complete multiple words at a time. For example, it
-can complete the command name abbreviation @code{p-b} into
-@code{print-buffer}, because no other command starts with two words
-whose initials are @samp{p} and @samp{b}. To enable this, use the
-command @kbd{M-x partial-completion-mode} or customize the option
-@code{partial-completion-mode}. Unless the option
-@code{PC-disable-includes} is @code{t}, Partial Completion mode also
-extends @kbd{M-x find-file} so that the @samp{<@dots{}>} sequence is
-interpreted as a file on the path @code{PC-include-file-path} and
-partial completion of file names is possible. Partial completion of
-directories in file names requires @samp{*}s to indicate the
-completions: @file{/u*/b*/f*} might expand to @file{/usr/bin/foo}. When
-Partial Completion mode is active, the Meta versions of the @kbd{TAB},
-@kbd{SPC}, @kbd{RET} and @kbd{?} keys act as those keys do by default
-for completion.
+ Another feature of Partial Completion mode is to extend
+@code{find-file} so that @samp{<@var{include}>} stands for the
+file named @var{include} in some directory in the path
+@code{PC-include-file-path}. If you set @code{PC-disable-includes} to
+non-@code{nil}, this feature is disabled.
@cindex Icomplete mode
@findex icomplete-mode
@findex previous-history-element
The simplest way to reuse the saved arguments in the history list is
to move through the history list one element at a time. While in the
-minibuffer, use @kbd{M-p} or up-arrow (@code{previous-history-element})
-to ``move to'' the next earlier minibuffer input, and use @kbd{M-n} or
-down-arrow (@code{next-history-element}) to ``move to'' the next later
-input.
+minibuffer, use @kbd{M-p} or up-arrow
+(@code{previous-history-element}) to ``move to'' the next earlier
+minibuffer input, and use @kbd{M-n} or down-arrow
+(@code{next-history-element}) to ``move to'' the next later input.
+These commands don't move the cursor, they bring different saved
+strings into the minibuffer. But you can think of them as ``moving''
+through the history list.
The previous input that you fetch from the history entirely replaces
the contents of the minibuffer. To use it as the argument, exit the
``moved'' to, but your new argument does go at the end of the history
list in its own right.
- For many minibuffer arguments there is a ``default'' value. In some
-cases, the minibuffer history commands know the default value. Then you
-can insert the default value into the minibuffer as text by using
-@kbd{M-n} to move ``into the future'' in the history. Eventually we
-hope to make this feature available whenever the minibuffer has a
-default value.
+ For many minibuffer arguments there is a ``default'' value. Then
+you can insert the default value into the minibuffer as text by using
+@kbd{M-n} to move ``into the future'' in the history.
@findex previous-matching-history-element
@findex next-matching-history-element
searches newer elements. By special dispensation, these commands can
use the minibuffer to read their arguments even though you are already
in the minibuffer when you issue them. As with incremental searching,
-an uppercase letter in the regular expression makes the search
+an upper-case letter in the regular expression makes the search
case-sensitive (@pxref{Search Case}).
@ignore
@code{history-length} is @code{t}, though, there is no maximum length
and elements are never deleted.
+@vindex history-delete-duplicates
+ The variable @code{history-delete-duplicates} specifies whether to
+delete duplicates in history. If the value of @code{history-delete-duplicates}
+is @code{t}, that means when adding a new history element, all
+previous identical elements are deleted.
+
@node Repetition
@section Repeating Minibuffer Commands
@cindex command history
the command name.
@findex list-command-history
-@c widecommands
@table @kbd
@item C-x @key{ESC} @key{ESC}
Re-execute a recent minibuffer command (@code{repeat-complex-command}).
you can edit its expression as usual and then resubmit it by typing
@key{RET} as usual.
+@vindex isearch-resume-in-command-history
+ Incremental search does not, strictly speaking, use the minibuffer,
+but it does something similar. Although it behaves like a complex command,
+it normally does not appear in the history list for @kbd{C-x
+@key{ESC} @key{ESC}}. You can make it appear in the history by
+setting @code{isearch-resume-in-command-history} to a non-@code{nil}
+value. @xref{Incremental Search}.
+
@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
can re-execute a command by calling @code{eval} with the
@code{command-history} element.
+
+@ignore
+ arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f
+@end ignore