X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/2311d8e5a62b8b6dd7dde45b4b8059d443e2abac..25f455815bfaa868dc470d445413df9a7a546c46:/doc/emacs/mini.texi diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index e498516ae7..be4206cb60 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -1,8 +1,9 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software +@c Foundation, Inc. @c See file emacs.texi for copying conditions. -@node Minibuffer, M-x, Basic, Top +@node Minibuffer @chapter The Minibuffer @cindex minibuffer @@ -13,24 +14,54 @@ 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. +@menu +* Basic Minibuffer:: Basic usage of 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. +* Yes or No Prompts:: Replying yes or no in the echo area. +@end menu + +@node Basic Minibuffer +@section Using the Minibuffer + @cindex prompt When the minibuffer is in use, it appears in the echo area, with a -cursor. The minibuffer starts with a @dfn{prompt} in a distinct -color, usually ending with a colon. The prompt states what kind of -input is expected, and how it will be used. +cursor. The minibuffer starts with a @dfn{prompt}, usually ending +with a colon. The prompt states what kind of input is expected, and +how it will be used. The prompt is highlighted using the +@code{minibuffer-prompt} face (@pxref{Faces}). 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}. +then @key{RET} to submit the argument and exit the minibuffer. +Alternatively, you can type @kbd{C-g} to exit the minibuffer by +canceling the command asking for the argument (@pxref{Quitting}). @cindex default argument - Sometimes, a @dfn{default argument} appears in the prompt, inside + Sometimes, the prompt shows a @dfn{default argument}, inside parentheses before the colon. This default will be used as the argument if you just type @key{RET}. For example, commands that read buffer names usually show a buffer name as the default; you can type @key{RET} to operate on that default buffer. +@cindex Minibuffer Electric Default mode +@cindex mode, Minibuffer Electric Default +@findex minibuffer-electric-default-mode +@vindex minibuffer-eldef-shorten-default + If you enable Minibuffer Electric Default mode, a global minor mode, +Emacs hides the default argument as soon as you modify the contents of +the minibuffer (since typing @key{RET} would no longer submit that +default). If you ever bring back the original minibuffer text, the +prompt again shows the default. Furthermore, if you change the +variable @code{minibuffer-eldef-shorten-default} to a non-@code{nil} +value, the default argument is displayed as @samp{[@var{default}]} +instead of @samp{(default @var{default})}, saving some screen space. +To enable this minor mode, type @kbd{M-x +minibuffer-electric-default-mode}. + Since the minibuffer appears in the echo area, it can conflict with other uses of the echo area. If an error message or an informative message is emitted while the minibuffer is active, the message hides @@ -38,15 +69,6 @@ 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 -* 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 @@ -87,8 +109,8 @@ Find file: /u2/emacs/src//etc/termcap @cindex double slash in file name @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, +A double slash causes Emacs to 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 @@ -197,7 +219,7 @@ 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. +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. @@ -315,8 +337,8 @@ used with the completion list: @table @kbd @findex mouse-choose-completion -@item Mouse-1 -@itemx Mouse-2 +@item mouse-1 +@itemx mouse-2 Clicking mouse button 1 or 2 on a completion alternative chooses it (@code{mouse-choose-completion}). @@ -336,12 +358,12 @@ While in the completion list buffer, this chooses the completion at point (@code{choose-completion}). @findex next-completion -@item @key{Right} +@item @key{RIGHT} While in the completion list buffer, this moves point to the following completion alternative (@code{next-completion}). @findex previous-completion -@item @key{Left} +@item @key{LEFT} While in the completion list buffer, this moves point to the previous completion alternative (@code{previous-completion}). @end table @@ -414,10 +436,10 @@ This behavior is used by most commands that read file names, like @cindex completion style Completion commands work by narrowing a large list of possible -completion alternatives to a smaller subset that ``matches'' what you +completion alternatives to a smaller subset that matches what you have typed in the minibuffer. In @ref{Completion Example}, we gave a simple example of such matching. The procedure of determining what -constitutes a ``match'' is quite intricate. Emacs attempts to offer +constitutes a match is quite intricate. Emacs attempts to offer plausible completions under most circumstances. Emacs performs completion using one or more @dfn{completion @@ -524,11 +546,14 @@ ignored as a completion alternative. Any element ending in a slash @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 +completions end in otherwise-ignored strings, they are not ignored: in the previous example, @samp{foo.e} completes to @samp{foo.elc}. Emacs disregards @code{completion-ignored-extensions} when showing completion alternatives in the completion list. + Shell completion is an extended version of filename completion, +@pxref{Shell 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 @@ -540,7 +565,7 @@ completion list buffer. @vindex completion-cycle-threshold If @code{completion-cycle-threshold} is non-@code{nil}, completion -commands can ``cycle'' through completion alternatives. Normally, if +commands can cycle through completion alternatives. Normally, if there is more than one completion alternative for the text in the minibuffer, a completion command completes up to the longest common substring. If you change @code{completion-cycle-threshold} to @@ -549,14 +574,7 @@ those completion alternatives; each subsequent invocation of the completion command replaces that with the next completion alternative, in a cyclic manner. If you give @code{completion-cycle-threshold} a numeric value @var{n}, completion commands switch to this cycling -behavior only when there are fewer than @var{n} alternatives. - -@cindex Icomplete mode -@findex icomplete-mode - Icomplete mode presents a constantly-updated display that tells you -what completions are available for the text you've entered so far. The -command to enable or disable this minor mode is @kbd{M-x -icomplete-mode}. +behavior only when there are @var{n} or fewer alternatives. @node Minibuffer History @section Minibuffer History @@ -570,13 +588,17 @@ argument into the minibuffer: @table @kbd @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 @key{UP} +@itemx @key{DOWN} +Like @kbd{M-p} and @kbd{M-n}, but move to the previous or next line of +a multi-line item before going to the previous history item +(@code{previous-line-or-history-element} and +@code{next-line-or-history-element}) . @item M-r @var{regexp} @key{RET} Move to an earlier item in the minibuffer history that matches @var{regexp} (@code{previous-matching-history-element}). @@ -591,21 +613,29 @@ Move to a later item in the minibuffer history that matches @kindex DOWN @r{(minibuffer history)} @findex next-history-element @findex previous-history-element - While in the minibuffer, @kbd{M-p} or @key{Up} -(@code{previous-history-element}) moves 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. -Typing @kbd{M-n} or @key{Down} (@code{next-history-element}) moves -through the minibuffer history list in the opposite direction, -fetching later entries into the minibuffer. + While in the minibuffer, @kbd{M-p} (@code{previous-history-element}) +moves 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. Typing @kbd{M-n} +(@code{next-history-element}) moves through the minibuffer history +list in the opposite direction, fetching later entries into the +minibuffer. 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 arguments: values that you are likely to enter. You can think of this -as moving through the ``future history'' list. +as moving through the ``future history''. - If you edit the text inserted by the @kbd{M-p} or @key{M-n} +@findex previous-line-or-history-element +@findex next-line-or-history-element + The arrow keys @kbd{@key{UP}} and @kbd{@key{DOWN}} work like +@kbd{M-p} and @kbd{M-n}, but if the current history item is longer +than a single line, they allow you to move to the previous or next +line of the current history item before going to the previous or next +history item. + + If you edit the text inserted by the @kbd{M-p} or @kbd{M-n} minibuffer history commands, this does not change its entry in the history list. However, the edited argument does go at the end of the history list when you submit it. @@ -624,8 +654,8 @@ expressions. A numeric prefix argument @var{n} means to fetch the @var{n}th matching entry. These commands are unusual, in that they use the minibuffer to read the regular expression argument, even though they are invoked from the minibuffer. An upper-case letter in -the regular expression makes the search case-sensitive (@pxref{Search -Case}). +the regular expression makes the search case-sensitive (@pxref{Lax +Search}). You can also search through the history using an incremental search. @xref{Isearch Minibuffer}. @@ -682,13 +712,13 @@ the text for that expression. Even if you don't know Lisp, it will probably be obvious which command is displayed for repetition. If you type just @key{RET}, that repeats the command unchanged. You can also change the command by editing the Lisp expression before you execute -it. The repeated command is added to the front of the command history +it. The executed command is added to the front of the command history unless it is identical to the most recent item. Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can use the usual minibuffer history commands (@pxref{Minibuffer History}) to move through the history list. After finding the desired -previous command, you can edit its expression as usual and then repeat +previous command, you can edit its expression as usual and then execute it by typing @key{RET}. @vindex isearch-resume-in-command-history @@ -726,10 +756,60 @@ 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 +backwards, removing the last character entered. @kbd{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. + +@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.