X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/fdc9061358d3654e14bfc1419632e1d6c6c5c13e..867d4bb3718f1fee9191e2c17cd810ef620d4b54:/doc/emacs/mini.texi diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index eb2a8e6546..3f6208c46e 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -1,98 +1,83 @@ @c This is part of the Emacs manual. @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Minibuffer, M-x, Basic, Top @chapter The Minibuffer @cindex minibuffer The @dfn{minibuffer} is where Emacs commands read complicated -arguments (anything more a single number). We call it the -``minibuffer'' because it's a special-purpose buffer with a small -amount of screen space. Minibuffer arguments can be file names, -buffer names, Lisp function names, Emacs command names, Lisp -expressions, and many other things---whatever the command wants to -read. You can use the usual Emacs editing commands in the minibuffer -to edit the argument text. +arguments, such as file names, buffer names, Emacs command names, or +Lisp expressions. We call it the ``minibuffer'' because it's a +special-purpose buffer with a small amount of screen space. You can +use the usual Emacs editing commands in the minibuffer to edit the +argument text. @cindex prompt When the minibuffer is in use, it appears in the echo area, with a cursor. The minibuffer display starts with a @dfn{prompt} in a -distinct color; it says what kind of input is expected and how it will -be used. Often the prompt is derived from the name of the command -that is reading the argument. The prompt normally ends with a colon. +distinct color, usually ending with a colon. The prompt states what +kind of input is expected, and how it will be used. + + The simplest way to enter a minibuffer argument is to type the text, +then @key{RET} to submit the argument and exit the minibuffer. You +can cancel the minibuffer, and the command that wants the argument, by +typing @kbd{C-g}. @cindex default argument - Sometimes a @dfn{default argument} appears in the prompt, inside + Sometimes, a @dfn{default argument} appears in the prompt, inside parentheses before the colon. The default will be used as the argument value if you just type @key{RET}. For example, commands that -read buffer names show a buffer name as the default. You can type -@key{RET} to operate on that default buffer. - - The simplest way to enter a minibuffer argument is to type the text, -then @key{RET} to exit the minibuffer. You can cancel the minibuffer, -and the command that wants the argument, by typing @kbd{C-g}. +read buffer names usually show a buffer name as the default; you can +type @key{RET} to operate on that default buffer. Since the minibuffer appears in the echo area, it can conflict with -other uses of the echo area. Here is how Emacs handles such -conflicts: - -@itemize @bullet -@item -An error occurs while the minibuffer is active. - -The error message hides the minibuffer for a few seconds, or until you -type something. Then the minibuffer comes back. - -@item -A command such as @kbd{C-x =} needs to display a message in the echo -area. - -The message hides the minibuffer for a few seconds, or until you type -something. Then the minibuffer comes back. - -@item -Keystrokes don't echo while the minibuffer is in use. -@end itemize +other uses of the echo area. If an error occurs while the minibuffer +is active, the error message hides the minibuffer for a few seconds, +or until you type something; then the minibuffer comes back. If a +command such as @kbd{C-x =} needs to display a message in the echo +area, the message hides the minibuffer for a few seconds, or until you +type something; then the minibuffer comes back. While the minibuffer +is in use, keystrokes do not echo. @menu -* File: Minibuffer File. Entering file names with the minibuffer. -* Edit: Minibuffer Edit. How to edit in the minibuffer. +* Minibuffer File:: Entering file names with the minibuffer. +* Minibuffer Edit:: How to edit in the minibuffer. * Completion:: An abbreviation facility for minibuffer input. * Minibuffer History:: Reusing recent minibuffer arguments. * Repetition:: Re-executing commands that used the minibuffer. +* Passwords:: Entering passwords in the echo area. @end menu @node Minibuffer File @section Minibuffers for File Names - When you use the minibuffer to enter a file name, it starts out with -some initial text---the @dfn{default directory}, ending in a slash. -The file you specify will be in this directory unless you alter or -replace it. - -@c Separate paragraph to clean up ugly page break--rms -@need 1500 - For example, if the minibuffer starts out with these contents: + Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer +to read a file name argument (@pxref{Basic Files}). When the +minibuffer is used to read a file name, it typically starts out with +some initial text ending in a slash. This is the @dfn{default +directory}. For example, it may start out like this: @example Find File: /u2/emacs/src/ @end example @noindent -(where @samp{Find File:@: } is the prompt), and you type -@kbd{buffer.c} as input, that specifies the file -@file{/u2/emacs/src/buffer.c}. You can specify the parent directory -by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you -will get @file{/u2/emacs/lisp/simple.el}. Alternatively, you can use -@kbd{M-@key{DEL}} to kill the directory names you don't want -(@pxref{Words}). - - You can kill the entire default with @kbd{C-a C-k}, but there's no -need to do that. It's easier to ignore the default, and enter an -absolute file name starting with a slash or a tilde after the default -directory. For example, to specify @file{/etc/termcap}, just type -that name: +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. + + You can specify the parent directory by adding @file{..}: for +example, @file{/u2/emacs/src/../lisp/simple.el} is equivalent to +@file{/u2/emacs/lisp/simple.el}. Alternatively, you can use +@kbd{M-@key{DEL}} to kill directory names backwards (@pxref{Words}). + + To specify a file in a completely different directory, you can kill +the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}). +Alternatively, you can ignore the default, and enter an absolute file +name starting with a slash or a tilde after the default directory. +For example, you can specify @file{/etc/termcap} as follows: @example Find File: /u2/emacs/src//etc/termcap @@ -103,59 +88,95 @@ Find File: /u2/emacs/src//etc/termcap @cindex double slash in file name @cindex slashes repeated in file name @findex file-name-shadow-mode -GNU Emacs interprets a double slash (which is not normally useful in -file names) as, ``ignore everything before the second slash in the -pair.'' In the example above. @samp{/u2/emacs/src/} is ignored, so -you get @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 Shadow mode (a minor mode) with the command -@kbd{M-x file-name-shadow-mode}. - - If the variable @code{insert-default-directory} is @code{nil}, the -default directory is never inserted in the minibuffer---so the -minibuffer starts out empty. Nonetheless, relative file name -arguments are still interpreted based on the same default directory. +Emacs interprets a double slash as ``ignore everything before the +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 +Shadow mode with the command @kbd{M-x file-name-shadow-mode}.) + +@cindex home directory shorthand + Emacs interprets @file{~/} as your home directory. Thus, +@file{~/foo/bar.txt} specifies a file named @file{bar.txt}, inside a +directory named @file{foo}, which is in turn located in your home +directory. In addition, @file{~@var{user-id}/} means the home +directory of a user whose login name is @var{user-id}. Any leading +directory name in front of the @file{~} is ignored: thus, +@file{/u2/emacs/~/foo/bar.txt} is equivalent to @file{~/foo/bar.txt}. + + On MS-Windows and MS-DOS systems, where a user doesn't always have a +home directory, Emacs uses several alternatives. For MS-Windows, see +@ref{Windows HOME}; for MS-DOS, see +@ifnottex +@ref{MS-DOS File Names, HOME on MS-DOS}. +@end ifnottex +@iftex +@ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the Emacs Manual}, in +the main Emacs manual. +@end iftex +On these systems, the @file{~@var{user-id}/} construct is supported +only for the current user, i.e., only if @var{user-id} is the current +user's login name. + +@vindex insert-default-directory + To prevent Emacs from inserting the default directory when reading +file names, change the variable @code{insert-default-directory} to +@code{nil}. In that case, the minibuffer starts out empty. +Nonetheless, relative file name arguments are still interpreted based +on the same default directory. @node Minibuffer Edit @section Editing in the Minibuffer - The minibuffer is an Emacs buffer (albeit a peculiar one), and the + The minibuffer is an Emacs buffer, albeit a peculiar one, and the usual Emacs commands are available for editing the argument text. +(The prompt, however, is @dfn{read-only}, and cannot be changed.) 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}. (The newline character is really the @acronym{ASCII} character control-J.) - The minibuffer has its own window, which normally has space in the -frame at all times, but it only acts like an Emacs window when the -minibuffer is active. When active, this window is much like any other -Emacs window; for instance, you can switch to another window (with -@kbd{C-x o}), edit text there, then return to the minibuffer window to -finish the argument. You can even kill text in another window, return -to the minibuffer window, and then yank the text into the argument. -@xref{Windows}. + Inside a minibuffer, the keys @kbd{@key{TAB}}, @kbd{@key{SPC}}, and +@kbd{@key{?}} are often bound to commands that perform +@dfn{completion}. @xref{Completion}. You can use @kbd{C-q} +(@code{quoted-insert}) to insert a @key{TAB}, @key{SPC}, or @key{?} +character. For example, @kbd{C-q @key{TAB}} inserts a @key{TAB} +character. @xref{Inserting Text}. + + For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a +minibuffer moves point to the beginning of the argument text, not the +beginning of the prompt. For example, this allows you to erase the +entire argument with @kbd{C-a C-k}. @cindex height of minibuffer @cindex size of minibuffer @cindex growing minibuffer @cindex resizing minibuffer - There are some restrictions on the minibuffer window, however: you -cannot kill it, or split it, or switch buffers in it---the minibuffer -and its window are permanently attached. + When the minibuffer is active, the echo area is treated much like an +ordinary Emacs window. For instance, you can switch to another window +(with @kbd{C-x o}), edit text there, then return to the minibuffer +window to finish the argument. You can even kill text in another +window, return to the minibuffer window, and yank the text into the +argument. There are some restrictions on the minibuffer window, +however: for instance, you cannot split it. @xref{Windows}. @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 always resizes as needed by its -contents. If its value is the symbol @code{grow-only}, the window -grows automatically as needed, 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. + Normally, the minibuffer window occupies a single screen line. +However, if you add two or more lines' worth of text into the +minibuffer, it expands automatically to accomodate the text. The +variable @code{resize-mini-windows} controls the resizing of the +minibuffer. The default value is @code{grow-only}, which means the +behavior we have just described. If the value is @code{t}, the +minibuffer window will also shrink automatically if you remove some +lines of text from the minibuffer, down to a minimum of one screen +line. If the value is @code{nil}, the minibuffer window never changes +size automatically, but you can use the usual window-resizing commands +on it (@pxref{Windows}). @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 +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. @@ -168,45 +189,40 @@ completions. @xref{Other Window}. @vindex enable-recursive-minibuffers Emacs normally disallows most commands that use the minibuffer while -the minibuffer is active. (Entering the minibuffer from the -minibuffer can be confusing.) To allow such commands in the -minibuffer, set the variable @code{enable-recursive-minibuffers} to -@code{t}. +the minibuffer is active. To allow such commands in the minibuffer, +set the variable @code{enable-recursive-minibuffers} to @code{t}. @node Completion @section Completion +@c This node is referenced in the tutorial. When renaming or deleting +@c it, the tutorial needs to be adjusted. @cindex completion - - Some arguments allow @dfn{completion} to enter their value. This -means that after you type part of the argument, Emacs can fill in the -rest, or some of it, based on what you have typed so far. - - When completion is available, certain keys---@key{TAB}, @key{RET}, -and @key{SPC}---are rebound to complete the text in the minibuffer -before point into a longer string chosen from a set of @dfn{completion -alternatives} provided by the command that requested the argument. -(@key{SPC} does not do completion in reading file names, because it is -common to use spaces in file names on some systems.) @kbd{?} displays -a list of the possible completions at any time. + + Sometimes, you can use a feature called @dfn{completion} to help you +enter arguments. This means that after you type part of the argument, +Emacs can fill in the rest, or some of it, based on what you have +typed so far. + + When completion is available, certain keys (usually @key{TAB}, +@key{RET}, and @key{SPC}) are rebound to complete the text in the +minibuffer into a longer string chosen from a set of @dfn{completion +alternatives}. The set of completion alternatives depends on the +command that requested the argument, and on what you have typed so +far. In addition, you can usually type @kbd{?} to display a list of +possible completions. For example, @kbd{M-x} uses the minibuffer to read the name of a -command, so it provides a list of all Emacs command names for -completion candidates. The completion keys match the minibuffer text -against these candidates, find any additional name characters implied -by the text already present in the minibuffer, and add those -characters. This 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. +command, so completion works by matching the minibuffer text against +the names of existing Emacs commands. So, to run the command +@code{insert-buffer}, you can type @kbd{M-x ins @key{SPC} b @key{RET}} +instead of the full @kbd{M-x insert-buffer @key{RET}}. Case is significant in completion when it is significant in the -argument you are entering (buffer names, file names, command names, -for instance). Thus, @samp{fo} does not complete to @samp{Foo}. +argument you are entering, such as command names. Thus, +@samp{insert-buffer} is not a valid completion for @samp{IN}. Completion ignores 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. Examples of using completion. * Commands: Completion Commands. A list of completion commands. @@ -218,22 +234,24 @@ typing some text into the minibuffer---it remains unchanged. @subsection Completion Example @kindex TAB @r{(completion)} - A concrete example may help here. If you type @kbd{M-x au + A concrete example may help here. If you type @kbd{M-x a u @key{TAB}}, the @key{TAB} looks for alternatives (in this case, command names) that start with @samp{au}. There are several, -including @code{auto-fill-mode} and @code{auto-save-mode}, but they -all begin with @code{auto-}, so the @samp{au} in the minibuffer -completes to @samp{auto-}. +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}. If you type @key{TAB} again immediately, it cannot determine the -next character; it could be any of @samp{cfilrs}. So it does not add -any characters; instead, @key{TAB} displays a list of all possible -completions in another window. +next character; it could be @samp{-}, @samp{a}, or @samp{c}. So it +does not add any characters; instead, @key{TAB} displays a list of all +possible completions in another window. - Now type @kbd{f @key{TAB}}. This @key{TAB} sees @samp{auto-f}. The -only command name starting with that is @code{auto-fill-mode}, so -completion fills in the rest of that. You have been able to enter -@samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}. + Next, type @kbd{- f}. The minibuffer now contains @samp{auto-f}, +and the only command name that starts with this is +@code{auto-fill-mode}. If you now type @key{TAB}, completion fills in +the rest of the argument @samp{auto-fill-mode} into the minibuffer. +You have been able to enter @samp{auto-fill-mode} by typing just +@kbd{a u @key{TAB} - f @key{TAB}}. @node Completion Commands @subsection Completion Commands @@ -244,7 +262,8 @@ when completion is allowed. @table @kbd @item @key{TAB} @findex minibuffer-complete -Complete the text before point in the minibuffer as much as possible +Complete the text before point in the minibuffer as much as possible; +if unable to complete, display a list of possible completions (@code{minibuffer-complete}). @item @key{SPC} Complete up to one word from the minibuffer text before point @@ -253,13 +272,12 @@ available when entering a file name, since file names often include spaces. @item @key{RET} Submit the text in the minibuffer as the argument, possibly completing -first as described +first as described in the next @iftex -in the next subsection (@code{minibuffer-complete-and-exit}). +subsection (@code{minibuffer-complete-and-exit}). @end iftex @ifnottex -in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict -Completion}. +node (@code{minibuffer-complete-and-exit}). @xref{Strict Completion}. @end ifnottex @item ? Display a list of possible completions of the text before point @@ -268,13 +286,12 @@ Display a list of possible completions of the text before point @kindex SPC @findex minibuffer-complete-word - @key{SPC} completes like @key{TAB}, but only up to the next hyphen -or space. If you have @samp{auto-f} in the minibuffer and type -@key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but -it only inserts @samp{ill-}, giving @samp{auto-fill-}. Another -@key{SPC} at this point completes all the way to -@samp{auto-fill-mode}. The command that implements this behavior is -called @code{minibuffer-complete-word}. + @key{SPC} (@code{minibuffer-complete-word}) completes like +@key{TAB}, but only up to the next hyphen or space. If you have +@samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the +completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-}, +giving @samp{auto-fill-}. Another @key{SPC} at this point completes +all the way to @samp{auto-fill-mode}. When you display a list of possible completions, you can choose one from it: @@ -284,34 +301,34 @@ one from it: @item Mouse-1 @itemx Mouse-2 Clicking mouse button 1 or 2 on a completion possibility chooses that -completion (@code{mouse-choose-completion}). You must click in the -list of completions, not in the minibuffer. +completion (@code{mouse-choose-completion}). @findex switch-to-completions -@item @key{PRIOR} -@itemx M-v -Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the -minibuffer, selects the window showing the completion list buffer -(@code{switch-to-completions}). This paves the way for using the -commands below. (Selecting that window in other ways has the same -effect.) +@item M-v +@itemx @key{PageUp} +@itemx @key{PRIOR} +Typing @kbd{M-v}, while in the minibuffer, selects the window showing +the completion list buffer (@code{switch-to-completions}). This paves +the way for using the commands below. Typing @key{PageUp} or +@key{PRIOR} does the same, as does selecting that window in other +ways. @findex choose-completion @item @key{RET} -Typing @key{RET} @emph{in the completion list buffer} chooses the +Typing @key{RET}, while in the completion list buffer, chooses the completion that point is in or next to (@code{choose-completion}). To use this command, you must first switch to the completion list window. @findex next-completion -@item @key{RIGHT} -Typing the right-arrow key @key{RIGHT} @emph{in the completion list -buffer} moves point to the following completion possibility +@item @key{Right} +Typing the right-arrow key @key{Right}, while in the completion list +buffer, moves point to the following completion possibility (@code{next-completion}). @findex previous-completion -@item @key{LEFT} -Typing the left-arrow key @key{LEFT} @emph{in the completion list -buffer} moves point to the previous completion possibility +@item @key{Left} +Typing the left-arrow key @key{Left}, while in the completion list +buffer, moves point to the previous completion possibility (@code{previous-completion}). @end table @@ -355,29 +372,34 @@ the list with @kbd{C-M-v} (@pxref{Other Window}). @node Completion Options @subsection Completion Options +@vindex completion-auto-help + If @code{completion-auto-help} is set to @code{nil}, the completion +commands never display the completion list buffer; you must type +@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 +completion list buffer. + @vindex completion-ignored-extensions @cindex ignored file names, in completion When completing file names, certain file names are usually ignored. The variable @code{completion-ignored-extensions} contains a list of strings; a file name ending in any of those strings is ignored as a completion candidate. The standard value of this variable has several -elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and -@code{"~"}. The effect is that, for example, @samp{foo} can complete -to @samp{foo.c} even though @samp{foo.o} exists as well. However, if -@emph{all} the possible completions end in ``ignored'' strings, then -they are not ignored. Displaying a list of possible completions -disregards @code{completion-ignored-extensions}; it shows them all. +elements including @code{".o"}, @code{".elc"}, and @code{"~"}. For +example, if a directory contains @samp{foo.c} and @samp{foo.elc}, +@samp{foo} completes to @samp{foo.c}. However, if @emph{all} possible +completions end in ``ignored'' strings, they are not ignored: in the +previous example, @samp{foo.e} completes to @samp{foo.elc}. +Displaying a list of possible completions disregards +@code{completion-ignored-extensions}; it shows them all. If an element of @code{completion-ignored-extensions} ends in a -slash (@file{/}), it's a subdirectory name; then that directory and -its contents are ignored. Elements of -@code{completion-ignored-extensions} which do not end in a slash are -ordinary file names, and do not apply to names of directories. - -@vindex completion-auto-help - If @code{completion-auto-help} is set to @code{nil}, the completion -commands never display a list of possibilities; you must type @kbd{?} -to display the list. +slash (@file{/}), it's a subdirectory name; that directory and its +contents are ignored. Elements of +@code{completion-ignored-extensions} that do not end in a slash are +ordinary file names. @cindex Partial Completion mode @vindex partial-completion-mode @@ -388,7 +410,7 @@ it can complete the command name abbreviation @code{p-b} into @code{print-buffer} if no other command starts with two words whose initials are @samp{p} and @samp{b}. - To enable this mode, use @kbd{M-x partial-completion-mode}, or + To enable this mode, use @kbd{M-x partial-completion-mode} or customize the variable @code{partial-completion-mode}. This mode binds special partial completion commands to @key{TAB}, @key{SPC}, @key{RET}, and @kbd{?} in the minibuffer. The usual completion @@ -421,19 +443,18 @@ icomplete-mode}. @cindex minibuffer history @cindex history of minibuffer input - Every argument that you enter with the minibuffer is saved on a + Every argument that you enter with the minibuffer is saved in a @dfn{minibuffer history list} so you can easily use it again later. -Special commands fetch the text of an earlier argument into the -minibuffer, replacing the old minibuffer contents. You can think of -them as moving through the history of previous arguments. +You can use the following arguments to quickly fetch an earlier +argument into the minibuffer: @table @kbd -@item @key{UP} -@itemx M-p -Move to the previous item in the minibuffer history, an earlier argument -(@code{previous-history-element}). -@item @key{DOWN} -@itemx M-n +@item M-p +@itemx @key{Up} +Move to the previous item in the minibuffer history, an earlier +argument (@code{previous-history-element}). +@item M-n +@itemx @key{Down} Move to the next item in the minibuffer history (@code{next-history-element}). @item M-r @var{regexp} @key{RET} @@ -448,24 +469,27 @@ Move to a later item in the minibuffer history that matches @kindex M-n @r{(minibuffer history)} @findex next-history-element @findex previous-history-element - To move through the minibuffer history list one item at a time, use -@kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the -next earlier minibuffer input, and use @kbd{M-n} or down-arrow -(@code{next-history-element}) to fetch the next later input. These -commands don't move the cursor, they pull different saved strings into -the minibuffer. But you can think of them as ``moving'' through the -history list. - - The input that you fetch from the history entirely replaces the -contents of the minibuffer. To use it again unchanged, just type -@key{RET}. You can also edit the text before you reuse it; this does -not change the history element that you ``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, or -a list of default values. You can insert the default value into the -minibuffer as text by using @kbd{M-n} one or more times. You can -think of this as moving ``into the future'' in the history. + While in the minibuffer, typing @kbd{M-p} or @key{Up} +(@code{previous-history-element}) moves up through the minibuffer +history list, one item at a time. Each @kbd{M-p} fetches an earlier +item from the history list into the minibuffer, replacing its existing +contents. Similarly, typing @kbd{M-n} or @key{Down} +(@code{next-history-element}) moves back down the history list, +fetching later entries into the minibuffer. You can think of these +commands as ``backwards'' and ``forwards'' through the history list. + + If you type @kbd{M-n} in the minibuffer when there are no later +entries in the minibuffer history (e.g., if you haven't previously +typed @kbd{M-p}), Emacs tries fetching from a list of default +argument: values that you are likely to enter. You can think of this +as moving through the ``future list'' instead of the ``history list''. + + The input that @kbd{M-p} or @kbd{M-n} fetches into the minibuffer +entirely replaces the existing contents of the minibuffer, so you can +simply type @key{RET} to use it as an argument. You can also edit the +text before you reuse it; this does not change the history element +that you ``moved'' to, but your new argument does go at the end of the +history list in its own right. @findex previous-matching-history-element @findex next-matching-history-element @@ -476,20 +500,12 @@ history; they search for history elements that match a regular expression. @kbd{M-r} (@code{previous-matching-history-element}) searches older elements in the history, while @kbd{M-s} (@code{next-matching-history-element}) searches newer elements. These -commands are unusual; they use the minibuffer to read the regular +commands are unusual: they use the minibuffer to read the regular expression even though they are invoked from the minibuffer. As with incremental searching, an upper-case letter in the regular expression -makes the search case-sensitive (@pxref{Search Case}). - -@ignore - We may change the precise way these commands read their arguments. -Perhaps they will search for a match for the string given so far in the -minibuffer; perhaps they will search for a literal match rather than a -regular expression match; perhaps they will only accept matches at the -beginning of a history element; perhaps they will read the string to -search for incrementally like @kbd{C-s}. To find out what interface is -actually available, type @kbd{C-h f previous-matching-history-element}. -@end ignore +makes the search case-sensitive (@pxref{Search Case}). You can also +search through the history using an incremental search (@pxref{Isearch +Minibuffer}). All uses of the minibuffer record your input on a history list, but there are separate history lists for different kinds of arguments. @@ -508,12 +524,13 @@ one used by @kbd{M-x} for command names, and one used by The variable @code{history-length} specifies the maximum length of a minibuffer history list; adding a new element deletes the oldest element if the list gets too long. If the value of -@code{history-length} is @code{t}, though, there is no maximum length. +@code{history-length} is @code{t}, there is no maximum length. @vindex history-delete-duplicates The variable @code{history-delete-duplicates} specifies whether to -delete duplicates in history. If it is @code{t}, adding a new element -deletes from the list all other elements that are equal to it. +delete duplicates in history. If it is non-@code{nil}, adding a new +element deletes from the list all other elements that are equal to it. +The default is @code{nil}. @node Repetition @section Repeating Minibuffer Commands @@ -575,6 +592,35 @@ 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. +@node Passwords +@section Entering passwords + +Sometimes, you may need to enter a password into Emacs. For instance, +when you tell Emacs to visit a file on another machine via a network +protocol such as FTP, you often need to supply a password to gain +access to the machine (@pxref{Remote Files}). + + Entering a password is, in a basic sense, similar to using a +minibuffer. Emacs displays a prompt in the echo area (such as +@samp{Password: }); after you type the required password, press +@key{RET} to submit it. To prevent others from seeing your password, +every character you type is displayed as a dot (@samp{.}) instead of +its usual form. + + Most of the features and commands associated with the minibuffer can +@emph{not} be used when entering a password. There is no history or +completion, and you cannot change windows or perform any other action +with Emacs until you have submitted the password. + + While you are typing the password, you may press @key{DEL} to delete +backwards, removing the last character entered. @key{C-u} deletes +everything you have typed so far. @kbd{C-g} quits the password prompt +(@pxref{Quitting}). @kbd{C-y} inserts the current kill into the +password (@pxref{Killing}). You may type either @key{RET} or +@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. + @ignore arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f @end ignore