Mercurial > emacs
annotate man/mini.texi @ 80452:6d01fa145e93
[!HAVE_CARBON]: Include Quickdraw.h instead of QuickDraw.h.
(XtPointer): Move typedef from macmenu.c.
(enum button_type): Move enum from macmenu.c.
(widget_value): Move typedef from macmenu.c.
(M_APPLE, I_ABOUT, EXTRA_STACK_ALLOC, ARGV_STRING_LIST_ID)
(DIALOG_LEFT_MARGIN, DIALOG_TOP_MARGIN, DIALOG_RIGHT_MARGIN)
(DIALOG_BOTTOM_MARGIN, DIALOG_MIN_INNER_WIDTH, DIALOG_MAX_INNER_WIDTH)
(DIALOG_BUTTON_BUTTON_HORIZONTAL_SPACE)
(DIALOG_BUTTON_BUTTON_VERTICAL_SPACE, DIALOG_BUTTON_MIN_WIDTH)
(DIALOG_TEXT_MIN_HEIGHT, DIALOG_TEXT_BUTTONS_VERTICAL_SPACE)
(DIALOG_ICON_WIDTH, DIALOG_ICON_HEIGHT, DIALOG_ICON_LEFT_MARGIN)
(DIALOG_ICON_TOP_MARGIN): Move defines from macmenu.c.
(Selection): Move typedef from macselect.c.
(RAM_TOO_LARGE_ALERT_ID, ABOUT_ALERT_ID) [MAC_OS8]: Move defines from
macterm.c.
(mac_set_window_title, mac_set_window_modified, mac_is_window_visible)
(mac_is_window_collapsed, mac_bring_window_to_front)
(mac_send_window_behind, mac_hide_window, mac_show_window)
(mac_collapse_window, mac_front_non_floating_window)
(mac_active_non_floating_window, mac_activate_window)
(mac_move_window_structure, mac_move_window, mac_size_window)
(mac_get_global_mouse, mac_is_window_toolbar_visible): New defines.
author | YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> |
---|---|
date | Sun, 06 Apr 2008 01:58:05 +0000 |
parents | 5f5e25959f89 |
children |
rev | line source |
---|---|
25829 | 1 @c This is part of the Emacs manual. |
64890
3723093a21fd
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
64375
diff
changeset
|
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, |
79791 | 3 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
25829 | 4 @c See file emacs.texi for copying conditions. |
5 @node Minibuffer, M-x, Basic, Top | |
6 @chapter The Minibuffer | |
7 @cindex minibuffer | |
8 | |
71207 | 9 The @dfn{minibuffer} is where Emacs commands read complicated |
10 arguments (anything more a single number). We call it the | |
11 ``minibuffer'' because it's a special-purpose buffer with a small | |
12 amount of screen space. Minibuffer arguments can be file names, | |
13 buffer names, Lisp function names, Emacs command names, Lisp | |
14 expressions, and many other things---whatever the command wants to | |
15 read. You can use the usual Emacs editing commands in the minibuffer | |
16 to edit the argument text. | |
25829 | 17 |
18 @cindex prompt | |
71207 | 19 When the minibuffer is in use, it appears in the echo area, with a |
20 cursor. The minibuffer display starts with a @dfn{prompt} in a | |
21 distinct color; it says what kind of input is expected and how it will | |
22 be used. Often the prompt is derived from the name of the command | |
23 that is reading the argument. The prompt normally ends with a colon. | |
25829 | 24 |
25 @cindex default argument | |
71207 | 26 Sometimes a @dfn{default argument} appears in the prompt, inside |
27 parentheses before the colon. The default will be used as the | |
28 argument value if you just type @key{RET}. For example, commands that | |
29 read buffer names show a buffer name as the default. You can type | |
30 @key{RET} to operate on that default buffer. | |
25829 | 31 |
71207 | 32 The simplest way to enter a minibuffer argument is to type the text, |
33 then @key{RET} to exit the minibuffer. You can cancel the minibuffer, | |
34 and the command that wants the argument, by typing @kbd{C-g}. | |
25829 | 35 |
71207 | 36 Since the minibuffer appears in the echo area, it can conflict with |
37 other uses of the echo area. Here is how Emacs handles such | |
38 conflicts: | |
25829 | 39 |
40 @itemize @bullet | |
41 @item | |
71207 | 42 An error occurs while the minibuffer is active. |
43 | |
44 The error message hides the minibuffer for a few seconds, or until you | |
45 type something. Then the minibuffer comes back. | |
25829 | 46 |
47 @item | |
71207 | 48 A command such as @kbd{C-x =} needs to display a message in the echo |
49 area. | |
50 | |
51 The message hides the minibuffer for a few seconds, or until you type | |
52 something. Then the minibuffer comes back. | |
25829 | 53 |
54 @item | |
71207 | 55 Keystrokes don't echo while the minibuffer is in use. |
25829 | 56 @end itemize |
57 | |
58 @menu | |
59 * File: Minibuffer File. Entering file names with the minibuffer. | |
60 * Edit: Minibuffer Edit. How to edit in the minibuffer. | |
61 * Completion:: An abbreviation facility for minibuffer input. | |
62 * Minibuffer History:: Reusing recent minibuffer arguments. | |
63 * Repetition:: Re-executing commands that used the minibuffer. | |
64 @end menu | |
65 | |
66 @node Minibuffer File | |
67 @section Minibuffers for File Names | |
68 | |
71207 | 69 When you use the minibuffer to enter a file name, it starts out with |
70 some initial text---the @dfn{default directory}, ending in a slash. | |
71 The file you specify will be in this directory unless you alter or | |
72 replace it. | |
25829 | 73 |
39265 | 74 @c Separate paragraph to clean up ugly page break--rms |
25829 | 75 @need 1500 |
71207 | 76 For example, if the minibuffer starts out with these contents: |
25829 | 77 |
78 @example | |
79 Find File: /u2/emacs/src/ | |
80 @end example | |
81 | |
82 @noindent | |
71207 | 83 (where @samp{Find File:@: } is the prompt), and you type |
84 @kbd{buffer.c} as input, that specifies the file | |
85 @file{/u2/emacs/src/buffer.c}. You can specify the parent directory | |
86 by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you | |
87 will get @file{/u2/emacs/lisp/simple.el}. Alternatively, you can use | |
88 @kbd{M-@key{DEL}} to kill the directory names you don't want | |
89 (@pxref{Words}). | |
25829 | 90 |
71494
37c66dd77b79
(Minibuffer File): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
71207
diff
changeset
|
91 You can kill the entire default with @kbd{C-a C-k}, but there's no |
37c66dd77b79
(Minibuffer File): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
71207
diff
changeset
|
92 need to do that. It's easier to ignore the default, and enter an |
37c66dd77b79
(Minibuffer File): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
71207
diff
changeset
|
93 absolute file name starting with a slash or a tilde after the default |
37c66dd77b79
(Minibuffer File): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
71207
diff
changeset
|
94 directory. For example, to specify @file{/etc/termcap}, just type |
37c66dd77b79
(Minibuffer File): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
71207
diff
changeset
|
95 that name: |
25829 | 96 |
97 @example | |
98 Find File: /u2/emacs/src//etc/termcap | |
99 @end example | |
100 | |
101 @noindent | |
102 @cindex // in file name | |
103 @cindex double slash in file name | |
104 @cindex slashes repeated in file name | |
66991
83e12e37521d
(Minibuffer File): Clarify previous change. Add @findex.
Richard M. Stallman <rms@gnu.org>
parents:
66953
diff
changeset
|
105 @findex file-name-shadow-mode |
71207 | 106 GNU Emacs interprets a double slash (which is not normally useful in |
107 file names) as, ``ignore everything before the second slash in the | |
108 pair.'' In the example above. @samp{/u2/emacs/src/} is ignored, so | |
109 you get @file{/etc/termcap}. The ignored part of the file name is | |
110 dimmed if the terminal allows it; to disable this dimming, turn off | |
111 File Name Shadow mode (a minor mode) with the command | |
112 @kbd{M-x file-name-shadow-mode}. | |
25829 | 113 |
71207 | 114 If the variable @code{insert-default-directory} is @code{nil}, the |
68458 | 115 default directory is never inserted in the minibuffer---so the |
71207 | 116 minibuffer starts out empty. Nonetheless, relative file name |
117 arguments are still interpreted based on the same default directory. | |
25829 | 118 |
119 @node Minibuffer Edit | |
120 @section Editing in the Minibuffer | |
121 | |
71207 | 122 The minibuffer is an Emacs buffer (albeit a peculiar one), and the |
123 usual Emacs commands are available for editing the argument text. | |
25829 | 124 |
125 Since @key{RET} in the minibuffer is defined to exit the minibuffer, | |
126 you can't use it to insert a newline in the minibuffer. To do that, | |
68458 | 127 type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the |
128 @acronym{ASCII} character control-J.) | |
25829 | 129 |
71207 | 130 The minibuffer has its own window, which normally has space in the |
131 frame at all times, but it only acts like an Emacs window when the | |
132 minibuffer is active. When active, this window is much like any other | |
133 Emacs window; for instance, you can switch to another window (with | |
134 @kbd{C-x o}), edit text there, then return to the minibuffer window to | |
135 finish the argument. You can even kill text in another window, return | |
136 to the minibuffer window, and then yank the text into the argument. | |
137 @xref{Windows}. | |
25829 | 138 |
139 @cindex height of minibuffer | |
140 @cindex size of minibuffer | |
141 @cindex growing minibuffer | |
27216
99ca9ac9c31a
Minibuffer resizing now automatic.
Dave Love <fx@gnu.org>
parents:
25829
diff
changeset
|
142 @cindex resizing minibuffer |
71207 | 143 There are some restrictions on the minibuffer window, however: you |
144 cannot kill it, or split it, or switch buffers in it---the minibuffer | |
145 and its window are permanently attached. | |
33310
7476be16909f
(Minibuffer Edit): Add description of
Gerd Moellmann <gerd@gnu.org>
parents:
31050
diff
changeset
|
146 |
7476be16909f
(Minibuffer Edit): Add description of
Gerd Moellmann <gerd@gnu.org>
parents:
31050
diff
changeset
|
147 @vindex resize-mini-windows |
38461
23f63206a867
Proofreading fixes from Chris Green <chris_e_green@yahoo.com>.
Eli Zaretskii <eliz@gnu.org>
parents:
36727
diff
changeset
|
148 The minibuffer window expands vertically as necessary to hold the |
60245
78a1812a9fd5
(Minibuffer): Prompts are highlighted.
Richard M. Stallman <rms@gnu.org>
parents:
59798
diff
changeset
|
149 text that you put in the minibuffer. If @code{resize-mini-windows} is |
71207 | 150 @code{t} (the default), the window always resizes as needed by its |
151 contents. If its value is the symbol @code{grow-only}, the window | |
152 grows automatically as needed, but shrinks (back to the normal size) | |
153 only when the minibuffer becomes inactive. If its value is | |
154 @code{nil}, you have to adjust the height yourself. | |
33310
7476be16909f
(Minibuffer Edit): Add description of
Gerd Moellmann <gerd@gnu.org>
parents:
31050
diff
changeset
|
155 |
7476be16909f
(Minibuffer Edit): Add description of
Gerd Moellmann <gerd@gnu.org>
parents:
31050
diff
changeset
|
156 @vindex max-mini-window-height |
36166
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
157 The variable @code{max-mini-window-height} controls the maximum |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
158 height for resizing the minibuffer window: a floating-point number |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
159 specifies a fraction of the frame's height; an integer specifies the |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
160 maximum number of lines; @code{nil} means do not resize the minibuffer |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
161 window automatically. The default value is 0.25. |
25829 | 162 |
71207 | 163 The @kbd{C-M-v} command in the minibuffer scrolls the help text from |
164 commands that display help text of any sort in another window. | |
165 @kbd{M-@key{PAGEUP}} and @kbd{M-@key{PAGEDOWN}} also operate on that | |
166 help text. This is especially useful with long lists of possible | |
60245
78a1812a9fd5
(Minibuffer): Prompts are highlighted.
Richard M. Stallman <rms@gnu.org>
parents:
59798
diff
changeset
|
167 completions. @xref{Other Window}. |
25829 | 168 |
169 @vindex enable-recursive-minibuffers | |
170 Emacs normally disallows most commands that use the minibuffer while | |
71207 | 171 the minibuffer is active. (Entering the minibuffer from the |
172 minibuffer can be confusing.) To allow such commands in the | |
173 minibuffer, set the variable @code{enable-recursive-minibuffers} to | |
174 @code{t}. | |
25829 | 175 |
176 @node Completion | |
177 @section Completion | |
80325
5f5e25959f89
Add `referenced in the tutorial' comments.
Reiner Steib <Reiner.Steib@gmx.de>
parents:
79791
diff
changeset
|
178 @c This node is referenced in the tutorial. When renaming or deleting |
5f5e25959f89
Add `referenced in the tutorial' comments.
Reiner Steib <Reiner.Steib@gmx.de>
parents:
79791
diff
changeset
|
179 @c it, the tutorial needs to be adjusted. |
25829 | 180 @cindex completion |
71207 | 181 |
182 Some arguments allow @dfn{completion} to enter their value. This | |
183 means that after you type part of the argument, Emacs can fill in the | |
184 rest, or some of it, based on what you have typed so far. | |
25829 | 185 |
71207 | 186 When completion is available, certain keys---@key{TAB}, @key{RET}, |
187 and @key{SPC}---are rebound to complete the text in the minibuffer | |
188 before point into a longer string chosen from a set of @dfn{completion | |
189 alternatives} provided by the command that requested the argument. | |
190 (@key{SPC} does not do completion in reading file names, because it is | |
191 common to use spaces in file names on some systems.) @kbd{?} displays | |
192 a list of the possible completions at any time. | |
25829 | 193 |
71207 | 194 For example, @kbd{M-x} uses the minibuffer to read the name of a |
195 command, so it provides a list of all Emacs command names for | |
196 completion candidates. The completion keys match the minibuffer text | |
197 against these candidates, find any additional name characters implied | |
71751 | 198 by the text already present in the minibuffer, and add those |
71207 | 199 characters. This makes it possible to type @kbd{M-x ins @key{SPC} b |
200 @key{RET}} instead of @kbd{M-x insert-buffer @key{RET}}, for example. | |
25829 | 201 |
71207 | 202 Case is significant in completion when it is significant in the |
203 argument you are entering (buffer names, file names, command names, | |
204 for instance). Thus, @samp{fo} does not complete to @samp{Foo}. | |
205 Completion ignores case distinctions for certain arguments in which | |
25829 | 206 case does not matter. |
207 | |
60798
e6d77fce1453
(Completion): Completion acts on text before point.
Richard M. Stallman <rms@gnu.org>
parents:
60473
diff
changeset
|
208 Completion acts only on the text before point. If there is text in |
e6d77fce1453
(Completion): Completion acts on text before point.
Richard M. Stallman <rms@gnu.org>
parents:
60473
diff
changeset
|
209 the minibuffer after point---i.e., if you move point backward after |
e6d77fce1453
(Completion): Completion acts on text before point.
Richard M. Stallman <rms@gnu.org>
parents:
60473
diff
changeset
|
210 typing some text into the minibuffer---it remains unchanged. |
e6d77fce1453
(Completion): Completion acts on text before point.
Richard M. Stallman <rms@gnu.org>
parents:
60473
diff
changeset
|
211 |
25829 | 212 @menu |
54474
3264fbd6f6f5
(Completion): Add description for menu items.
Juri Linkov <juri@jurta.org>
parents:
52401
diff
changeset
|
213 * Example: Completion Example. Examples of using completion. |
3264fbd6f6f5
(Completion): Add description for menu items.
Juri Linkov <juri@jurta.org>
parents:
52401
diff
changeset
|
214 * Commands: Completion Commands. A list of completion commands. |
3264fbd6f6f5
(Completion): Add description for menu items.
Juri Linkov <juri@jurta.org>
parents:
52401
diff
changeset
|
215 * Strict Completion:: Different types of completion. |
3264fbd6f6f5
(Completion): Add description for menu items.
Juri Linkov <juri@jurta.org>
parents:
52401
diff
changeset
|
216 * Options: Completion Options. Options for completion. |
25829 | 217 @end menu |
218 | |
219 @node Completion Example | |
220 @subsection Completion Example | |
221 | |
222 @kindex TAB @r{(completion)} | |
71207 | 223 A concrete example may help here. If you type @kbd{M-x au |
224 @key{TAB}}, the @key{TAB} looks for alternatives (in this case, | |
225 command names) that start with @samp{au}. There are several, | |
226 including @code{auto-fill-mode} and @code{auto-save-mode}, but they | |
227 all begin with @code{auto-}, so the @samp{au} in the minibuffer | |
228 completes to @samp{auto-}. | |
25829 | 229 |
71207 | 230 If you type @key{TAB} again immediately, it cannot determine the |
231 next character; it could be any of @samp{cfilrs}. So it does not add | |
232 any characters; instead, @key{TAB} displays a list of all possible | |
233 completions in another window. | |
25829 | 234 |
71207 | 235 Now type @kbd{f @key{TAB}}. This @key{TAB} sees @samp{auto-f}. The |
236 only command name starting with that is @code{auto-fill-mode}, so | |
237 completion fills in the rest of that. You have been able to enter | |
238 @samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}. | |
25829 | 239 |
240 @node Completion Commands | |
241 @subsection Completion Commands | |
242 | |
243 Here is a list of the completion commands defined in the minibuffer | |
71207 | 244 when completion is allowed. |
25829 | 245 |
246 @table @kbd | |
247 @item @key{TAB} | |
71207 | 248 @findex minibuffer-complete |
46038
3d861934169e
Completion operates on text before point.
Richard M. Stallman <rms@gnu.org>
parents:
44373
diff
changeset
|
249 Complete the text before point in the minibuffer as much as possible |
25829 | 250 (@code{minibuffer-complete}). |
251 @item @key{SPC} | |
71207 | 252 Complete up to one word from the minibuffer text before point |
253 (@code{minibuffer-complete-word}). @key{SPC} for completion is not | |
254 available when entering a file name, since file names often include | |
255 spaces. | |
25829 | 256 @item @key{RET} |
257 Submit the text in the minibuffer as the argument, possibly completing | |
62333
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
258 first as described |
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
259 @iftex |
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
260 in the next subsection (@code{minibuffer-complete-and-exit}). |
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
261 @end iftex |
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
262 @ifnottex |
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
263 in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict |
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
264 Completion}. |
80f8fd5fdea6
(Completion Commands): Correct reference.
Luc Teirlinck <teirllm@auburn.edu>
parents:
60798
diff
changeset
|
265 @end ifnottex |
25829 | 266 @item ? |
71207 | 267 Display a list of possible completions of the text before point |
64375
32f868f94f5a
(Completion Commands): Fix command name for ?.
Richard M. Stallman <rms@gnu.org>
parents:
62333
diff
changeset
|
268 (@code{minibuffer-completion-help}). |
25829 | 269 @end table |
270 | |
271 @kindex SPC | |
272 @findex minibuffer-complete-word | |
71207 | 273 @key{SPC} completes like @key{TAB}, but only up to the next hyphen |
274 or space. If you have @samp{auto-f} in the minibuffer and type | |
275 @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but | |
276 it only inserts @samp{ill-}, giving @samp{auto-fill-}. Another | |
277 @key{SPC} at this point completes all the way to | |
278 @samp{auto-fill-mode}. The command that implements this behavior is | |
279 called @code{minibuffer-complete-word}. | |
25829 | 280 |
71207 | 281 When you display a list of possible completions, you can choose |
282 one from it: | |
25829 | 283 |
284 @table @kbd | |
285 @findex mouse-choose-completion | |
60245
78a1812a9fd5
(Minibuffer): Prompts are highlighted.
Richard M. Stallman <rms@gnu.org>
parents:
59798
diff
changeset
|
286 @item Mouse-1 |
78a1812a9fd5
(Minibuffer): Prompts are highlighted.
Richard M. Stallman <rms@gnu.org>
parents:
59798
diff
changeset
|
287 @itemx Mouse-2 |
71207 | 288 Clicking mouse button 1 or 2 on a completion possibility chooses that |
289 completion (@code{mouse-choose-completion}). You must click in the | |
290 list of completions, not in the minibuffer. | |
25829 | 291 |
292 @findex switch-to-completions | |
293 @item @key{PRIOR} | |
294 @itemx M-v | |
295 Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the | |
296 minibuffer, selects the window showing the completion list buffer | |
297 (@code{switch-to-completions}). This paves the way for using the | |
71207 | 298 commands below. (Selecting that window in other ways has the same |
299 effect.) | |
25829 | 300 |
301 @findex choose-completion | |
302 @item @key{RET} | |
303 Typing @key{RET} @emph{in the completion list buffer} chooses the | |
304 completion that point is in or next to (@code{choose-completion}). To | |
71207 | 305 use this command, you must first switch to the completion list window. |
25829 | 306 |
307 @findex next-completion | |
308 @item @key{RIGHT} | |
309 Typing the right-arrow key @key{RIGHT} @emph{in the completion list | |
71207 | 310 buffer} moves point to the following completion possibility |
311 (@code{next-completion}). | |
25829 | 312 |
313 @findex previous-completion | |
314 @item @key{LEFT} | |
315 Typing the left-arrow key @key{LEFT} @emph{in the completion list | |
71207 | 316 buffer} moves point to the previous completion possibility |
317 (@code{previous-completion}). | |
25829 | 318 @end table |
319 | |
320 @node Strict Completion | |
321 @subsection Strict Completion | |
322 | |
71207 | 323 There are three different ways that @key{RET} can do completion, |
324 depending on how the argument will be used. | |
25829 | 325 |
326 @itemize @bullet | |
327 @item | |
71207 | 328 @dfn{Strict} completion accepts only known completion candidates. For |
329 example, when @kbd{C-x k} reads the name of a buffer to kill, only the | |
330 name of an existing buffer makes sense. In strict completion, | |
331 @key{RET} refuses to exit if the text in the minibuffer does not | |
332 complete to an exact match. | |
25829 | 333 |
334 @item | |
335 @dfn{Cautious} completion is similar to strict completion, except that | |
71207 | 336 @key{RET} exits only if the text is an already exact match. |
337 Otherwise, @key{RET} does not exit, but it does complete the text. If | |
338 that completes to an exact match, a second @key{RET} will exit. | |
25829 | 339 |
340 Cautious completion is used for reading file names for files that must | |
71207 | 341 already exist, for example. |
25829 | 342 |
343 @item | |
71207 | 344 @dfn{Permissive} completion allows any input; the completion |
345 candidates are just suggestions. For example, when @kbd{C-x C-f} | |
346 reads the name of a file to visit, any file name is allowed, including | |
347 nonexistent file (in case you want to create a file). In permissive | |
348 completion, @key{RET} does not complete, it just submits the argument | |
349 as you have entered it. | |
25829 | 350 @end itemize |
351 | |
71207 | 352 The completion commands display a list of all possible completions |
353 whenever they can't determine even one more character by completion. | |
354 Also, typing @kbd{?} explicitly requests such a list. You can scroll | |
355 the list with @kbd{C-M-v} (@pxref{Other Window}). | |
25829 | 356 |
357 @node Completion Options | |
358 @subsection Completion Options | |
359 | |
360 @vindex completion-ignored-extensions | |
36289
931b5c1e2d14
(Completion Options): Add an index for "ignored file names".
Eli Zaretskii <eliz@gnu.org>
parents:
36167
diff
changeset
|
361 @cindex ignored file names, in completion |
71207 | 362 When completing file names, certain file names are usually ignored. |
363 The variable @code{completion-ignored-extensions} contains a list of | |
364 strings; a file name ending in any of those strings is ignored as a | |
365 completion candidate. The standard value of this variable has several | |
366 elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and | |
367 @code{"~"}. The effect is that, for example, @samp{foo} can complete | |
368 to @samp{foo.c} even though @samp{foo.o} exists as well. However, if | |
369 @emph{all} the possible completions end in ``ignored'' strings, then | |
370 they are not ignored. Displaying a list of possible completions | |
371 disregards @code{completion-ignored-extensions}; it shows them all. | |
25829 | 372 |
71207 | 373 If an element of @code{completion-ignored-extensions} ends in a |
374 slash (@file{/}), it's a subdirectory name; then that directory and | |
375 its contents are ignored. Elements of | |
39880
de2f745df406
(Completion Options): Document the significance of a trailing slash
Eli Zaretskii <eliz@gnu.org>
parents:
39265
diff
changeset
|
376 @code{completion-ignored-extensions} which do not end in a slash are |
71207 | 377 ordinary file names, and do not apply to names of directories. |
39880
de2f745df406
(Completion Options): Document the significance of a trailing slash
Eli Zaretskii <eliz@gnu.org>
parents:
39265
diff
changeset
|
378 |
25829 | 379 @vindex completion-auto-help |
71207 | 380 If @code{completion-auto-help} is set to @code{nil}, the completion |
381 commands never display a list of possibilities; you must type @kbd{?} | |
382 to display the list. | |
25829 | 383 |
28129 | 384 @cindex Partial Completion mode |
385 @vindex partial-completion-mode | |
386 @findex partial-completion-mode | |
36166
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
387 Partial Completion mode implements a more powerful kind of |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
388 completion that can complete multiple words in parallel. For example, |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
389 it can complete the command name abbreviation @code{p-b} into |
71207 | 390 @code{print-buffer} if no other command starts with two words whose |
391 initials are @samp{p} and @samp{b}. | |
392 | |
393 To enable this mode, use @kbd{M-x partial-completion-mode}, or | |
394 customize the variable @code{partial-completion-mode}. This mode | |
395 binds special partial completion commands to @key{TAB}, @key{SPC}, | |
396 @key{RET}, and @kbd{?} in the minibuffer. The usual completion | |
397 commands are available on @kbd{M-@key{TAB}} (or @kbd{C-M-i}), | |
398 @kbd{M-@key{SPC}}, @kbd{M-@key{RET}} and @kbd{M-?}. | |
36166
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
399 |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
400 Partial completion of directories in file names uses @samp{*} to |
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
401 indicate the places for completion; thus, @file{/u*/b*/f*} might |
71207 | 402 complete to @file{/usr/bin/foo}. For remote files, partial completion |
403 enables completion of methods, user names and host names. | |
404 @xref{Remote Files}. | |
36166
7ce22edfb862
Clean up max-mini-window-height and Partial Completion mode.
Richard M. Stallman <rms@gnu.org>
parents:
33310
diff
changeset
|
405 |
28129 | 406 @vindex PC-include-file-path |
407 @vindex PC-disable-includes | |
71207 | 408 Partial Completion mode also extends @code{find-file} so that |
409 @samp{<@var{include}>} looks for the file named @var{include} in the | |
410 directories in the path @code{PC-include-file-path}. If you set | |
411 @code{PC-disable-includes} to non-@code{nil}, this feature is | |
412 disabled. | |
25829 | 413 |
414 @cindex Icomplete mode | |
28129 | 415 @findex icomplete-mode |
25829 | 416 Icomplete mode presents a constantly-updated display that tells you |
417 what completions are available for the text you've entered so far. The | |
418 command to enable or disable this minor mode is @kbd{M-x | |
419 icomplete-mode}. | |
420 | |
421 @node Minibuffer History | |
422 @section Minibuffer History | |
423 @cindex minibuffer history | |
424 @cindex history of minibuffer input | |
425 | |
426 Every argument that you enter with the minibuffer is saved on a | |
71207 | 427 @dfn{minibuffer history list} so you can easily use it again later. |
428 Special commands fetch the text of an earlier argument into the | |
429 minibuffer, replacing the old minibuffer contents. You can think of | |
430 them as moving through the history of previous arguments. | |
25829 | 431 |
432 @table @kbd | |
433 @item @key{UP} | |
434 @itemx M-p | |
71207 | 435 Move to the previous item in the minibuffer history, an earlier argument |
25829 | 436 (@code{previous-history-element}). |
437 @item @key{DOWN} | |
438 @itemx M-n | |
71207 | 439 Move to the next item in the minibuffer history |
25829 | 440 (@code{next-history-element}). |
441 @item M-r @var{regexp} @key{RET} | |
71207 | 442 Move to an earlier item in the minibuffer history that |
443 matches @var{regexp} (@code{previous-matching-history-element}). | |
25829 | 444 @item M-s @var{regexp} @key{RET} |
71207 | 445 Move to a later item in the minibuffer history that matches |
446 @var{regexp} (@code{next-matching-history-element}). | |
25829 | 447 @end table |
448 | |
449 @kindex M-p @r{(minibuffer history)} | |
450 @kindex M-n @r{(minibuffer history)} | |
451 @findex next-history-element | |
452 @findex previous-history-element | |
71207 | 453 To move through the minibuffer history list one item at a time, use |
454 @kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the | |
455 next earlier minibuffer input, and use @kbd{M-n} or down-arrow | |
456 (@code{next-history-element}) to fetch the next later input. These | |
457 commands don't move the cursor, they pull different saved strings into | |
458 the minibuffer. But you can think of them as ``moving'' through the | |
459 history list. | |
25829 | 460 |
71207 | 461 The input that you fetch from the history entirely replaces the |
462 contents of the minibuffer. To use it again unchanged, just type | |
463 @key{RET}. You can also edit the text before you reuse it; this does | |
464 not change the history element that you ``moved'' to, but your new | |
465 argument does go at the end of the history list in its own right. | |
25829 | 466 |
71207 | 467 For many minibuffer arguments there is a ``default'' value. You can |
468 insert the default value into the minibuffer as text by using | |
469 @kbd{M-n}. You can think of this as moving ``into the future'' in the | |
470 history. | |
25829 | 471 |
472 @findex previous-matching-history-element | |
473 @findex next-matching-history-element | |
474 @kindex M-r @r{(minibuffer history)} | |
475 @kindex M-s @r{(minibuffer history)} | |
476 There are also commands to search forward or backward through the | |
477 history; they search for history elements that match a regular | |
71207 | 478 expression. @kbd{M-r} (@code{previous-matching-history-element}) |
479 searches older elements in the history, while @kbd{M-s} | |
480 (@code{next-matching-history-element}) searches newer elements. These | |
481 commands are unusual; they use the minibuffer to read the regular | |
482 expression even though they are invoked from the minibuffer. As with | |
483 incremental searching, an upper-case letter in the regular expression | |
484 makes the search case-sensitive (@pxref{Search Case}). | |
25829 | 485 |
486 @ignore | |
487 We may change the precise way these commands read their arguments. | |
488 Perhaps they will search for a match for the string given so far in the | |
489 minibuffer; perhaps they will search for a literal match rather than a | |
490 regular expression match; perhaps they will only accept matches at the | |
491 beginning of a history element; perhaps they will read the string to | |
492 search for incrementally like @kbd{C-s}. To find out what interface is | |
493 actually available, type @kbd{C-h f previous-matching-history-element}. | |
494 @end ignore | |
495 | |
496 All uses of the minibuffer record your input on a history list, but | |
71207 | 497 there are separate history lists for different kinds of arguments. |
498 For example, there is a list for file names, used by all the commands | |
499 that read file names. (As a special feature, this history list | |
500 records the absolute file name, even if the name you entered was not | |
501 absolute.) | |
25829 | 502 |
71207 | 503 There are several other specific history lists, including one for |
504 buffer names, one for arguments of commands like @code{query-replace}, | |
505 one used by @kbd{M-x} for command names, and one used by | |
506 @code{compile} for compilation commands. Finally, there is one | |
507 ``miscellaneous'' history list that most minibuffer arguments use. | |
25829 | 508 |
509 @vindex history-length | |
510 The variable @code{history-length} specifies the maximum length of a | |
71207 | 511 minibuffer history list; adding a new element deletes the oldest |
512 element if the list gets too long. If the value of | |
513 @code{history-length} is @code{t}, though, there is no maximum length. | |
25829 | 514 |
57017
9f99ae07c452
(Minibuffer History): Add `history-delete-duplicates'.
Juri Linkov <juri@jurta.org>
parents:
54474
diff
changeset
|
515 @vindex history-delete-duplicates |
9f99ae07c452
(Minibuffer History): Add `history-delete-duplicates'.
Juri Linkov <juri@jurta.org>
parents:
54474
diff
changeset
|
516 The variable @code{history-delete-duplicates} specifies whether to |
71207 | 517 delete duplicates in history. If it is @code{t}, adding a new element |
518 deletes from the list all other elements that are equal to it. | |
57017
9f99ae07c452
(Minibuffer History): Add `history-delete-duplicates'.
Juri Linkov <juri@jurta.org>
parents:
54474
diff
changeset
|
519 |
25829 | 520 @node Repetition |
521 @section Repeating Minibuffer Commands | |
522 @cindex command history | |
523 @cindex history of commands | |
524 | |
71207 | 525 Every command that uses the minibuffer once is recorded on a special |
526 history list, the @dfn{command history}, together with the values of | |
527 its arguments, so that you can repeat the entire command. In | |
528 particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} | |
529 uses the minibuffer to read the command name. | |
25829 | 530 |
531 @findex list-command-history | |
532 @table @kbd | |
533 @item C-x @key{ESC} @key{ESC} | |
71207 | 534 Re-execute a recent minibuffer command from the command history |
535 (@code{repeat-complex-command}). | |
25829 | 536 @item M-x list-command-history |
537 Display the entire command history, showing all the commands | |
538 @kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. | |
539 @end table | |
540 | |
541 @kindex C-x ESC ESC | |
542 @findex repeat-complex-command | |
71207 | 543 @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command |
544 that used the minibuffer. With no argument, it repeats the last such | |
545 command. A numeric argument specifies which command to repeat; 1 | |
546 means the last one, 2 the previous, and so on. | |
25829 | 547 |
548 @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command | |
549 into a Lisp expression and then entering a minibuffer initialized with | |
71207 | 550 the text for that expression. Even if you don't understand Lisp |
551 syntax, it will probably be obvious which command is displayed for | |
552 repetition. If you type just @key{RET}, that repeats the command | |
553 unchanged. You can also change the command by editing the Lisp | |
554 expression before you execute it. The repeated command is added to | |
555 the front of the command history unless it is identical to the most | |
556 recently item. | |
25829 | 557 |
558 Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can | |
559 use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, | |
560 @kbd{M-s}; @pxref{Minibuffer History}) to move through the history list | |
561 of saved entire commands. After finding the desired previous command, | |
71207 | 562 you can edit its expression as usual and then repeat it by typing |
563 @key{RET}. | |
25829 | 564 |
57080
82fe8e8f2ffe
(Repetition): Rename isearch-resume-enabled to
Kim F. Storm <storm@cua.dk>
parents:
57017
diff
changeset
|
565 @vindex isearch-resume-in-command-history |
71207 | 566 Incremental search does not, strictly speaking, use the minibuffer. |
567 Therefore, although it behaves like a complex command, it normally | |
568 does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. | |
569 You can make incremental search commands appear in the history by | |
57080
82fe8e8f2ffe
(Repetition): Rename isearch-resume-enabled to
Kim F. Storm <storm@cua.dk>
parents:
57017
diff
changeset
|
570 setting @code{isearch-resume-in-command-history} to a non-@code{nil} |
60245
78a1812a9fd5
(Minibuffer): Prompts are highlighted.
Richard M. Stallman <rms@gnu.org>
parents:
59798
diff
changeset
|
571 value. @xref{Incremental Search}. |
46038
3d861934169e
Completion operates on text before point.
Richard M. Stallman <rms@gnu.org>
parents:
44373
diff
changeset
|
572 |
25829 | 573 @vindex command-history |
574 The list of previous minibuffer-using commands is stored as a Lisp | |
575 list in the variable @code{command-history}. Each element is a Lisp | |
576 expression which describes one command and its arguments. Lisp programs | |
577 can re-execute a command by calling @code{eval} with the | |
578 @code{command-history} element. | |
52401 | 579 |
580 @ignore | |
581 arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f | |
582 @end ignore |