Mercurial > hg > xemacs-beta

comparison man/xemacs/mini.texi @ 398:74fd4e045ea6 r21-2-29

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-29
author cvs
date Mon, 13 Aug 2007 11:13:30 +0200
parents 376386a54a3c
children 501cfd01ee6d
comparison
equal deleted inserted replaced
397:f4aeb21a5bad 398:74fd4e045ea6
1 1
2 @node Minibuffer, M-x, Undo, Top 2 @node Minibuffer, M-x, Undo, Top
3 @chapter The Minibuffer 3 @chapter The Minibuffer
4 @cindex minibuffer 4 @cindex minibuffer
5 5
6 Emacs commands use the @dfn{minibuffer} to read arguments more 6 The @dfn{minibuffer} is the facility used by XEmacs commands to read
7 complicated than a single number. Minibuffer arguments can be file 7 arguments more complicated than a single number. Minibuffer arguments
8 names, buffer names, Lisp function names, Emacs command names, Lisp 8 can be file names, buffer names, Lisp function names, XEmacs command
9 expressions, and many other things, depending on the command reading the 9 names, Lisp expressions, and many other things, depending on the command
10 argument. To edit the argument in the minibuffer, you can use Emacs 10 reading the argument. You can use the usual XEmacs editing commands in
11 editing commands. 11 the minibuffer to edit the argument text.
12
13 12
14 @cindex prompt 13 @cindex prompt
15 When the minibuffer is in use, it appears in the echo area, and the 14 When the minibuffer is in use, it appears in the echo area, and the
16 cursor moves there. The beginning of the minibuffer line displays a 15 cursor moves there. The beginning of the minibuffer line displays a
17 @dfn{prompt} indicating what kind of input you should supply and how it 16 @dfn{prompt} which says what kind of input you should supply and how it
18 will be used. The prompt is often derived from the name of the command 17 will be used. Often this prompt is derived from the name of the command
19 the argument is for. The prompt normally ends with a colon. 18 that the argument is for. The prompt normally ends with a colon.
20 19
21 @cindex default argument 20 @cindex default argument
22 Sometimes a @dfn{default argument} appears in parentheses after the 21 Sometimes a @dfn{default argument} appears in parentheses after the
23 colon; it, too, is part of the prompt. The default is used as the 22 colon; it, too, is part of the prompt. The default is used as the
24 argument value if you enter an empty argument (e.g., by just typing @key{RET}). 23 argument value if you enter an empty argument (e.g., by just typing @key{RET}).
25 For example, commands that read buffer names always show a default, which 24 For example, commands that read buffer names always show a default, which
26 is the name of the buffer that will be used if you type just @key{RET}. 25 is the name of the buffer that will be used if you type just @key{RET}.
27 26
28 @kindex C-g 27 @kindex C-g
29 The simplest way to give a minibuffer argument is to type the text you 28 The simplest way to enter a minibuffer argument is to type the text
30 want, terminated by @key{RET} to exit the minibuffer. To get out 29 you want, terminated by @key{RET} which exits the minibuffer. You can
31 of the minibuffer and cancel the command that it was for, type 30 cancel the command that wants the argument, and get out of the
32 @kbd{C-g}. 31 minibuffer, by typing @kbd{C-g}.
33 32
34 Since the minibuffer uses the screen space of the echo area, it can 33 Since the minibuffer uses the screen space of the echo area, it can
35 conflict with other ways Emacs customarily uses the echo area. Here is how 34 conflict with other ways XEmacs customarily uses the echo area. Here is
36 Emacs handles such conflicts: 35 how XEmacs handles such conflicts:
37 36
38 @itemize @bullet 37 @itemize @bullet
39 @item 38 @item
40 If a command gets an error while you are in the minibuffer, this does 39 If a command gets an error while you are in the minibuffer, this does
41 not cancel the minibuffer. However, the echo area is needed for the 40 not cancel the minibuffer. However, the echo area is needed for the
42 error message and therefore the minibuffer itself is hidden for a 41 error message and therefore the minibuffer itself is hidden for a
43 while. It comes back after a few seconds, or as soon as you type 42 while. It comes back after a few seconds, or as soon as you type
44 anything. 43 anything.
45 44
46 @item 45 @item
47 If you use a command in the minibuffer whose purpose is to print a 46 If in the minibuffer you use a command whose purpose is to print a
48 message in the echo area (for example @kbd{C-x =}) the message is 47 message in the echo area, such as @kbd{C-x =}, the message is printed
49 displayed normally, and the minibuffer is hidden for a while. It comes back 48 normally, and the minibuffer is hidden for a while. It comes back
50 after a few seconds, or as soon as you type anything. 49 after a few seconds, or as soon as you type anything.
51 50
52 @item 51 @item
53 Echoing of keystrokes does not take place while the minibuffer is in 52 Echoing of keystrokes does not take place while the minibuffer is in
54 use. 53 use.
56 55
57 @menu 56 @menu
58 * File: Minibuffer File. Entering file names with the minibuffer. 57 * File: Minibuffer File. Entering file names with the minibuffer.
59 * Edit: Minibuffer Edit. How to edit in the minibuffer. 58 * Edit: Minibuffer Edit. How to edit in the minibuffer.
60 * Completion:: An abbreviation facility for minibuffer input. 59 * Completion:: An abbreviation facility for minibuffer input.
60 * Minibuffer History:: Reusing recent minibuffer arguments.
61 * Repetition:: Re-executing commands that used the minibuffer. 61 * Repetition:: Re-executing commands that used the minibuffer.
62 @end menu 62 @end menu
63 63
64 @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer 64 @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
65 @section Minibuffers for File Names 65 @section Minibuffers for File Names
66 66
67 Sometimes the minibuffer starts out with text in it. For example, when 67 Sometimes the minibuffer starts out with text in it. For example, when
68 you are supposed to give a file name, the minibuffer starts out containing 68 you are supposed to give a file name, the minibuffer starts out containing
69 the @dfn{default directory}, which ends with a slash. This informs 69 the @dfn{default directory}, which ends with a slash. This is to inform
70 you in which directory the file will be looked for if you do not specify 70 you which directory the file will be found in if you do not specify a
71 a different one. For example, the minibuffer might start out with: 71 directory.
72
73 For example, the minibuffer might start out with these contents:
72 74
73 @example 75 @example
74 Find File: /u2/emacs/src/ 76 Find File: /u2/emacs/src/
75 @end example 77 @end example
76 78
77 @noindent 79 @noindent
78 where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} specifies 80 where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c}
79 the file 81 specifies the file @file{/u2/emacs/src/buffer.c}. To find files in
80 @*@file{/u2/emacs/src/buffer.c}. To find files in nearby 82 nearby directories, use @kbd{..}; thus, if you type
81 directories, use @samp{..}; thus, if you type @kbd{../lisp/simple.el}, the 83 @kbd{../lisp/simple.el}, you will get the file named
82 file that you visit will be the one named 84 @file{/u2/emacs/lisp/simple.el}. Alternatively, you can kill with
83 @*@file{/u2/emacs/lisp/simple.el}. 85 @kbd{M-@key{DEL}} the directory names you don't want (@pxref{Words}).
84 Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names you 86
85 don't want (@pxref{Words}).@refill 87 If you don't want any of the default, you can kill it with @kbd{C-a
86 88 C-k}. But you don't need to kill the default; you can simply ignore it.
87 You can also type an absolute file name, one starting with a slash or a 89 Insert an absolute file name, one starting with a slash or a tilde,
88 tilde, ignoring the default directory. For example, to find the file 90 after the default directory. For example, to specify the file
89 @file{/etc/termcap}, just type the name, giving: 91 @file{/etc/termcap}, just insert that name, giving these minibuffer
92 contents:
90 93
91 @example 94 @example
92 Find File: /u2/emacs/src//etc/termcap 95 Find File: /u2/emacs/src//etc/termcap
93 @end example 96 @end example
94 97
95 @noindent 98 @noindent
96 Two slashes in a row are not normally meaningful in Unix file names, but 99 @cindex // in file name
97 they are allowed in XEmacs. They mean, ``ignore everything before the 100 @cindex double slash in file name
98 second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored, and 101 @cindex slashes repeated in file name
99 you get the file @file{/etc/termcap}. 102 XEmacs gives a special meaning to a double slash (which is not normally
103 a useful thing to write): it means, ``ignore everything before the
104 second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored in
105 the example above, and you get the file @file{/etc/termcap}.
100 106
101 @vindex insert-default-directory 107 @vindex insert-default-directory
102 If you set @code{insert-default-directory} to @code{nil}, the default 108 If you set @code{insert-default-directory} to @code{nil}, the default
103 directory is not inserted in the minibuffer. This way, the minibuffer 109 directory is not inserted in the minibuffer. This way, the minibuffer
104 starts out empty. But the name you type, if relative, is still 110 starts out empty. But the name you type, if relative, is still
105 interpreted with respect to the same default directory. 111 interpreted with respect to the same default directory.
106 112
107 @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer 113 @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
108 @section Editing in the Minibuffer 114 @section Editing in the Minibuffer
109 115
110 The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual 116 The minibuffer is an XEmacs buffer (albeit a peculiar one), and the
111 Emacs commands are available for editing the text of an argument you are 117 usual XEmacs commands are available for editing the text of an argument
112 entering. 118 you are entering.
113 119
114 Since @key{RET} in the minibuffer is defined to exit the minibuffer, 120 Since @key{RET} in the minibuffer is defined to exit the minibuffer,
115 you must use @kbd{C-o} or @kbd{C-q @key{LFD}} to insert a newline into 121 you can't use it to insert a newline in the minibuffer. To do that,
116 the minibuffer. (Recall that a newline is really the @key{LFD} 122 type @kbd{C-o} or @kbd{C-q C-j}. (Recall that a newline is really the
117 character.) 123 character control-J.)
118 124
119 The minibuffer has its own window, which always has space on the screen 125 The minibuffer has its own window which always has space on the screen
120 but acts as if it were not there when the minibuffer is not in use. The 126 but acts as if it were not there when the minibuffer is not in use.
121 minibuffer window is just like the others; you can switch to another 127 When the minibuffer is in use, its window is just like the others; you
122 window with @kbd{C-x o}, edit text in other windows, and perhaps even 128 can switch to another window with @kbd{C-x o}, edit text in other
123 visit more files before returning to the minibuffer to submit the 129 windows and perhaps even visit more files, before returning to the
124 argument. You can kill text in another window, return to the minibuffer 130 minibuffer to submit the argument. You can kill text in another window,
125 window, and then yank the text to use it in the argument. @xref{Windows}. 131 return to the minibuffer window, and then yank the text to use it in the
126 132 argument. @xref{Windows}.
127 There are, however, some restrictions on the use of the minibuffer window. 133
128 You cannot switch buffers in it---the minibuffer and its window are 134 There are some restrictions on the use of the minibuffer window,
129 permanently attached. You also cannot split or kill the minibuffer 135 however. You cannot switch buffers in it---the minibuffer and its
130 window, but you can make it taller with @kbd{C-x ^}. 136 window are permanently attached. Also, you cannot split or kill the
137 minibuffer window. But you can make it taller in the normal fashion with
138 @kbd{C-x ^}.
131 139
132 @kindex C-M-v 140 @kindex C-M-v
133 If you are in the minibuffer and issue a command that displays help 141 If while in the minibuffer you issue a command that displays help text
134 text in another window, that window will be scrolled if you type 142 of any sort in another window, you can use the @kbd{C-M-v} command while
135 @kbd{M-C-v} while in the minibuffer until you exit the minibuffer. This 143 in the minibuffer to scroll the help text. This lasts until you exit
136 feature is helpful if a completing minibuffer gives you a long list of 144 the minibuffer. This feature is especially useful if a completing
137 possible completions. 145 minibuffer gives you a list of possible completions. @xref{Other Window}.
138 146
147 @vindex minibuffer-confirm-incomplete
139 If the variable @code{minibuffer-confirm-incomplete} is @code{t}, you 148 If the variable @code{minibuffer-confirm-incomplete} is @code{t}, you
140 are asked for confirmation if there is no known completion for the text 149 are asked for confirmation if there is no known completion for the text
141 you typed. For example, if you attempted to visit a non-existent file, 150 you typed. For example, if you attempted to visit a non-existent file,
142 the minibuffer might read: 151 the minibuffer might read:
143 @example 152 @example
144 Find File:chocolate_bar.c [no completions, confirm] 153 Find File: chocolate_bar.c [no completions, confirm]
145 @end example 154 @end example
146 If you press @kbd{Return} again, that confirms the filename. Otherwise, 155 If you press @kbd{Return} again, that confirms the filename. Otherwise,
147 you can continue editing it. 156 you can continue editing it.
148 157
149 Emacs supports recursive use of the minibuffer. However, it is 158 XEmacs supports recursive use of the minibuffer. However, it is easy
150 easy to do this by accident (because of autorepeating keyboards, for 159 to do this by accident (because of autorepeating keyboards, for example)
151 example) and get confused. Therefore, most Emacs commands that use the 160 and get confused. Therefore, most XEmacs commands that use the
152 minibuffer refuse to operate if the minibuffer window is selected. If the 161 minibuffer refuse to operate if the minibuffer window is selected. If
153 minibuffer is active but you have switched to a different window, recursive 162 the minibuffer is active but you have switched to a different window,
154 use of the minibuffer is allowed---if you know enough to try to do this, 163 recursive use of the minibuffer is allowed---if you know enough to try
155 you probably will not get confused. 164 to do this, you probably will not get confused.
156 165
157 @vindex enable-recursive-minibuffers 166 @vindex enable-recursive-minibuffers
158 If you set the variable @code{enable-recursive-minibuffers} to be 167 If you set the variable @code{enable-recursive-minibuffers} to a
159 non-@code{nil}, recursive use of the minibuffer is always allowed. 168 non-@code{nil}, recursive use of the minibuffer is always allowed.
160 169
161 @node Completion, Repetition, Minibuffer Edit, Minibuffer 170 @node Completion, Minibuffer History, Minibuffer Edit, Minibuffer
162 @section Completion 171 @section Completion
163 @cindex completion 172 @cindex completion
164 173
165 When appropriate, the minibuffer provides a @dfn{completion} facility. 174 For certain kinds of arguments, you can use @dfn{completion} to enter
166 You type the beginning of an argument and one of the completion keys, 175 the argument value. Completion means that you type part of the
167 and Emacs visibly fills in the rest, depending on what you have already 176 argument, then XEmacs visibly fills in the rest, or as much as
168 typed. 177 can be determined from the part you have typed.
169 178
170 When completion is available, certain keys---@key{TAB}, @key{RET}, and 179 When completion is available, certain keys---@key{TAB}, @key{RET}, and
171 @key{SPC}---are redefined to complete an abbreviation present in the 180 @key{SPC}---are rebound to complete the text present in the
172 minibuffer into a longer string that it stands for, by matching it 181 minibuffer into a longer string that it stands for, by matching it
173 against a set of @dfn{completion alternatives} provided by the command 182 against a set of @dfn{completion alternatives} provided by the command
174 reading the argument. @kbd{?} is defined to display a list of possible 183 reading the argument. @kbd{?} is defined to display a list of possible
175 completions of what you have inserted. 184 completions of what you have inserted.
176 185
177 For example, when the minibuffer is being used by @kbd{Meta-x} to read 186 For example, when @kbd{M-x} uses the minibuffer to read the name of a
178 the name of a command, it is given a list of all available Emacs command 187 command, it provides a list of all available XEmacs command names to
179 names to complete against. The completion keys match the text in the 188 complete against. The completion keys match the text in the minibuffer
180 minibuffer against all the command names, find any additional characters of 189 against all the command names, find any additional name characters
181 the name that are implied by the ones already present in the minibuffer, 190 implied by the ones already present in the minibuffer, and add those
182 and add those characters to the ones you have given. 191 characters to the ones you have given. This is what makes it possible
183 192 to type @kbd{M-x inse @key{SPC} b @key{RET}} instead of @kbd{M-x
184 Case is normally significant in completion because it is significant in 193 insert-buffer @key{RET}} (for example).
185 most of the names that you can complete (buffer names, file names, and 194
186 command names). Thus, @samp{fo} will not complete to @samp{Foo}. When you 195 Case is normally significant in completion because it is significant
187 are completing a name in which case does not matter, case may be ignored 196 in most of the names that you can complete (buffer names, file names and
188 for completion's sake if specified by program. 197 command names). Thus, @samp{fo} does not complete to @samp{Foo}. When
198 you are completing a name in which case does not matter, case may be
199 ignored for completion's sake if specified by program.
189 200
190 When a completion list is displayed, the completions will highlight as 201 When a completion list is displayed, the completions will highlight as
191 you move the mouse over them. Clicking the middle mouse button on any 202 you move the mouse over them. Clicking the middle mouse button on any
192 highlighted completion will ``select'' it just as if you had typed it in 203 highlighted completion will ``select'' it just as if you had typed it in
193 and hit @key{RET}. 204 and hit @key{RET}.
194 205
195 @subsection A Completion Example 206 @menu
207 * Example: Completion Example.
208 * Commands: Completion Commands.
209 * Strict Completion::
210 * Options: Completion Options.
211 @end menu
212
213 @node Completion Example, Completion Commands, Completion, Completion
214 @subsection Completion Example
196 215
197 @kindex TAB 216 @kindex TAB
198 @findex minibuffer-complete 217 @findex minibuffer-complete
199 Consider the following example. If you type @kbd{Meta-x au @key{TAB}}, 218 A concrete example may help here. If you type @kbd{M-x au @key{TAB}},
200 @key{TAB} looks for alternatives (in this case, command names) that 219 the @key{TAB} looks for alternatives (in this case, command names) that
201 start with @samp{au}. There are only two commands: @code{auto-fill-mode} and 220 start with @samp{au}. There are several, including
202 @code{auto-save-mode}. They are the same as far as @code{auto-}, so the 221 @code{auto-fill-mode} and @code{auto-save-mode}---but they are all the
203 @samp{au} in the minibuffer changes to @samp{auto-}.@refill 222 same as far as @code{auto}, so the @samp{au} in the minibuffer changes
204 223 to @samp{auto}.
205 If you type @key{TAB} again immediately, there are multiple possibilities 224
206 for the very next character---it could be @samp{s} or @samp{f}---so no more 225 If you type @key{TAB} again immediately, there are multiple
207 characters are added; but a list of all possible completions is displayed 226 possibilities for the very next character---it could be any of
208 in another window. 227 @samp{c-}---so no more characters are added; instead, @key{TAB}
228 displays a list of all possible completions in another window.
209 229
210 If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees 230 If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees
211 @samp{auto-f}. The only command name starting this way is 231 @samp{auto-f}. The only command name starting this way is
212 @code{auto-fill-mode}, so completion inserts the rest of that command. You 232 @code{auto-fill-mode}, so completion fills in the rest of that. You now
213 now have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au 233 have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
214 @key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in the 234 @key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in
215 minibuffer it is bound to the function @code{minibuffer-complete} when 235 the minibuffer it is bound to the command @code{minibuffer-complete}
216 completion is supposed to be done.@refill 236 when completion is available.
217 237
238 @node Completion Commands, Strict Completion, Completion Example, Completion
218 @subsection Completion Commands 239 @subsection Completion Commands
219 240
220 Here is a list of all the completion commands defined in the minibuffer 241 Here is a list of the completion commands defined in the minibuffer
221 when completion is available. 242 when completion is available.
222 243
223 @table @kbd 244 @table @kbd
224 @item @key{TAB} 245 @item @key{TAB}
225 Complete the text in the minibuffer as much as possible @* 246 Complete the text in the minibuffer as much as possible
226 (@code{minibuffer-complete}). 247 (@code{minibuffer-complete}).
227 @item @key{SPC} 248 @item @key{SPC}
228 Complete the text in the minibuffer but don't add or fill out more 249 Complete the minibuffer text, but don't go beyond one word
229 than one word (@code{minibuffer-complete-word}). 250 (@code{minibuffer-complete-word}).
230 @item @key{RET} 251 @item @key{RET}
231 Submit the text in the minibuffer as the argument, possibly completing 252 Submit the text in the minibuffer as the argument, possibly completing
232 first as described below (@code{minibuffer-complete-and-exit}). 253 first as described below (@code{minibuffer-complete-and-exit}).
233 @item ? 254 @item ?
234 Print a list of all possible completions of the text in the minibuffer 255 Print a list of all possible completions of the text in the minibuffer
242 (@code{minibuf-select-highlighted-completion}). 263 (@code{minibuf-select-highlighted-completion}).
243 @end table 264 @end table
244 265
245 @kindex SPC 266 @kindex SPC
246 @findex minibuffer-complete-word 267 @findex minibuffer-complete-word
247 @key{SPC} completes in a way that is similar to @key{TAB}, but it never 268 @key{SPC} completes much like @key{TAB}, but never goes beyond the
248 goes beyond the next hyphen or space. If you have @samp{auto-f} in the 269 next hyphen or space. If you have @samp{auto-f} in the minibuffer and
249 minibuffer and type @key{SPC}, it finds that the completion is 270 type @key{SPC}, it finds that the completion is @samp{auto-fill-mode},
250 @samp{auto-fill-mode}, but it stops completing after @samp{fill-}. 271 but it stops completing after @samp{fill-}. This gives
251 The result is @samp{auto-fill-}. Another @key{SPC} at this point 272 @samp{auto-fill-}. Another @key{SPC} at this point completes all the
252 completes all the way to @samp{auto-fill-mode}. @key{SPC} in the 273 way to @samp{auto-fill-mode}. @key{SPC} in the minibuffer when
253 minibuffer runs the function @code{minibuffer-complete-word} when 274 completion is available runs the command
254 completion is available.@refill 275 @code{minibuffer-complete-word}.
276
277 Here are some commands you can use to choose a completion from a
278 window that displays a list of completions:
279
280 @table @kbd
281 @findex mouse-choose-completion
282 @item button2up
283 Clicking mouse button 2 on a completion in the list of possible
284 completions chooses that completion (@code{mouse-choose-completion}).
285 You normally use this command while point is in the minibuffer; but you
286 must click in the list of completions, not in the minibuffer itself.
287
288 @findex choose-completion
289 @item @key{RET}
290 Typing @key{RET} @emph{in the completion list buffer} chooses the
291 completion that point is in or next to (@code{choose-completion}). To
292 use this command, you must first switch windows to the window that shows
293 the list of completions.
294
295 @findex next-list-mode-item
296 @item @key{RIGHT}
297 @itemx @key{TAB}
298 @itemx C-f
299 Typing the right-arrow key @key{RIGHT}, @key{TAB} or @kbd{C-f} @emph{in
300 the completion list buffer} moves point to the following completion
301 (@code{next-list-mode-item}).
302
303 @findex previous-list-mode-item
304 @item @key{LEFT}
305 @itemx C-b
306 Typing the left-arrow key @key{LEFT} or @kbd{C-b} @emph{in the
307 completion list buffer} moves point toward the beginning of the buffer,
308 to the previous completion (@code{previous-list-mode-item}).
309 @end table
310
311 @node Strict Completion, Completion Options, Completion Commands, Completion
312 @subsection Strict Completion
255 313
256 There are three different ways that @key{RET} can work in completing 314 There are three different ways that @key{RET} can work in completing
257 minibuffers, depending on how the argument will be used. 315 minibuffers, depending on how the argument will be used.
258 316
259 @itemize @bullet 317 @itemize @bullet
274 332
275 Cautious completion is used for reading file names for files that must 333 Cautious completion is used for reading file names for files that must
276 already exist. 334 already exist.
277 335
278 @item 336 @item
279 @dfn{Permissive} completion is used when any string is 337 @dfn{Permissive} completion is used when any string whatever is
280 meaningful, and the list of completion alternatives is just a guide. 338 meaningful, and the list of completion alternatives is just a guide.
281 For example, when @kbd{C-x C-f} reads the name of a file to visit, any 339 For example, when @kbd{C-x C-f} reads the name of a file to visit, any
282 file name is allowed, in case you want to create a file. In 340 file name is allowed, in case you want to create a file. In
283 permissive completion, @key{RET} takes the text in the minibuffer 341 permissive completion, @key{RET} takes the text in the minibuffer
284 exactly as given, without completing it. 342 exactly as given, without completing it.
285 @end itemize 343 @end itemize
286 344
287 The completion commands display a list of all possible completions in a 345 The completion commands display a list of all possible completions in
288 window whenever there is more than one possibility for the very next 346 a window whenever there is more than one possibility for the very next
289 character. Typing @kbd{?} explicitly requests such a list. The 347 character. Also, typing @kbd{?} explicitly requests such a list. If
290 list of completions counts as help text, so @kbd{C-M-v} typed in the 348 the list of completions is long, you can scroll it with @kbd{C-M-v}
291 minibuffer scrolls the list. 349 (@pxref{Other Window}).
350
351 @node Completion Options, , Strict Completion, Completion
352 @subsection Completion Options
292 353
293 @vindex completion-ignored-extensions 354 @vindex completion-ignored-extensions
294 When completion is done on file names, certain file names are usually 355 When completion is done on file names, certain file names are usually
295 ignored. The variable @code{completion-ignored-extensions} contains a list 356 ignored. The variable @code{completion-ignored-extensions} contains a
296 of strings; a file whose name ends in any of those strings is ignored as a 357 list of strings; a file whose name ends in any of those strings is
297 possible completion. The standard value of this variable has several 358 ignored as a possible completion. The standard value of this variable
298 elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and @code{"~"}. 359 has several elements including @code{".o"}, @code{".elc"}, @code{".dvi"}
299 The effect is that, for example, @samp{foo} completes to @samp{foo.c} 360 and @code{"~"}. The effect is that, for example, @samp{foo} can
300 even though @samp{foo.o} exists as well. If the only possible completions 361 complete to @samp{foo.c} even though @samp{foo.o} exists as well.
301 are files that end in ``ignored'' strings, they are not ignored.@refill 362 However, if @emph{all} the possible completions end in ``ignored''
363 strings, then they are not ignored. Ignored extensions do not apply to
364 lists of completions---those always mention all possible completions.
302 365
303 @vindex completion-auto-help 366 @vindex completion-auto-help
304 If a completion command finds the next character is undetermined, it 367 If a completion command finds the next character is undetermined, it
305 automatically displays a list of all possible completions. If the variable 368 automatically displays a list of all possible completions. If the variable
306 @code{completion-auto-help} is set to @code{nil}, this does not happen, 369 @code{completion-auto-help} is set to @code{nil}, this does not happen,
310 If the variable @code{minibuffer-confirm-incomplete} is set to @code{t}, 373 If the variable @code{minibuffer-confirm-incomplete} is set to @code{t},
311 then in contexts where @code{completing-read} allows answers that are 374 then in contexts where @code{completing-read} allows answers that are
312 not valid completions, an extra @key{RET} must be typed to confirm the 375 not valid completions, an extra @key{RET} must be typed to confirm the
313 response. This is helpful for catching typos. 376 response. This is helpful for catching typos.
314 377
315 @node Repetition,, Completion, Minibuffer 378 @node Minibuffer History, Repetition, Completion, Minibuffer
379 @section Minibuffer History
380 @cindex minibuffer history
381 @cindex history of minibuffer input
382
383 Every argument that you enter with the minibuffer is saved on a
384 @dfn{minibuffer history list} so that you can use it again later in
385 another argument. Special commands load the text of an earlier argument
386 in the minibuffer. They discard the old minibuffer contents, so you can
387 think of them as moving through the history of previous arguments.
388
389 @table @kbd
390 @item @key{UP}
391 @itemx M-p
392 Move to the next earlier argument string saved in the minibuffer history
393 (@code{previous-history-element}).
394 @item @key{DOWN}
395 @itemx M-n
396 Move to the next later argument string saved in the minibuffer history
397 (@code{next-history-element}).
398 @item M-r @var{regexp} @key{RET}
399 Move to an earlier saved argument in the minibuffer history that has a
400 match for @var{regexp} (@code{previous-matching-history-element}).
401 @item M-s @var{regexp} @key{RET}
402 Move to a later saved argument in the minibuffer history that has a
403 match for @var{regexp} (@code{next-matching-history-element}).
404 @end table
405
406 @kindex M-p @r{(minibuffer history)}
407 @kindex M-n @r{(minibuffer history)}
408 @findex next-history-element
409 @findex previous-history-element
410 The simplest way to reuse the saved arguments in the history list is
411 to move through the history list one element at a time. While in the
412 minibuffer, use @kbd{M-p} or up-arrow (@code{previous-history-element})
413 to ``move to'' the next earlier minibuffer input, and use @kbd{M-n} or
414 down-arrow (@code{next-history-element}) to ``move to'' the next later
415 input.
416
417 The previous input that you fetch from the history entirely replaces
418 the contents of the minibuffer. To use it as the argument, exit the
419 minibuffer as usual with @key{RET}. You can also edit the text before
420 you reuse it; this does not change the history element that you
421 ``moved'' to, but your new argument does go at the end of the history
422 list in its own right.
423
424 For many minibuffer arguments there is a ``default'' value. In some
425 cases, the minibuffer history commands know the default value. Then you
426 can insert the default value into the minibuffer as text by using
427 @kbd{M-n} to move ``into the future'' in the history.
428
429 @findex previous-matching-history-element
430 @findex next-matching-history-element
431 @kindex M-r @r{(minibuffer history)}
432 @kindex M-s @r{(minibuffer history)}
433 There are also commands to search forward or backward through the
434 history; they search for history elements that match a regular
435 expression that you specify with the minibuffer. @kbd{M-r}
436 (@code{previous-matching-history-element}) searches older elements in
437 the history, while @kbd{M-s} (@code{next-matching-history-element})
438 searches newer elements. By special dispensation, these commands can
439 use the minibuffer to read their arguments even though you are already
440 in the minibuffer when you issue them. As with incremental searching,
441 an uppercase letter in the regular expression makes the search
442 case-sensitive (@pxref{Search Case}).
443
444 All uses of the minibuffer record your input on a history list, but
445 there are separate history lists for different kinds of arguments. For
446 example, there is a list for file names, used by all the commands that
447 read file names.
448
449 There are several other very specific history lists, including one for
450 command names read by @kbd{M-x}, one for buffer names, one for arguments
451 of commands like @code{query-replace}, and one for compilation commands
452 read by @code{compile}. Finally, there is one ``miscellaneous'' history
453 list that most minibuffer arguments use.
454
455 @c Do wee need this?
456 @ignore
457 @vindex history-length
458 The variable @code{history-length} specifies the maximum length of a
459 minibuffer history list; once a list gets that long, the oldest element
460 is deleted each time an element is added. If the value of
461 @code{history-length} is @code{t}, though, there is no maximum length
462 and elements are never deleted.
463 @end ignore
464
465 @node Repetition, , Minibuffer History, Minibuffer
316 @section Repeating Minibuffer Commands 466 @section Repeating Minibuffer Commands
317 @cindex command history 467 @cindex command history
318 @cindex history of commands 468 @cindex history of commands
319 469
320 Every command that uses the minibuffer at least once is recorded on a 470 Every command that uses the minibuffer at least once is recorded on a
321 special history list, together with the values of the minibuffer arguments, 471 special history list, together with the values of its arguments, so that
322 so that you can repeat the command easily. In particular, every 472 you can repeat the entire command. In particular, every use of
323 use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to 473 @kbd{M-x} is recorded there, since @kbd{M-x} uses the minibuffer to read
324 read the command name. 474 the command name.
325 475
326 @findex list-command-history 476 @findex list-command-history
327 @c widecommands 477 @c widecommands
328 @table @kbd 478 @table @kbd
329 @item C-x @key{ESC} 479 @item C-x @key{ESC} @key{ESC}
330 Re-execute a recent minibuffer command @*(@code{repeat-complex-command}). 480 Re-execute a recent minibuffer command (@code{repeat-complex-command}).
331 @item M-p 481 @item M-p
332 Within @kbd{C-x @key{ESC}}, move to previous recorded command 482 Within @kbd{C-x @key{ESC}}, move to previous recorded command
333 (@code{previous-history-element}). 483 (@code{previous-history-element}).
334 @item M-n 484 @item M-n
335 Within @kbd{C-x @key{ESC}}, move to the next (more recent) recorded 485 Within @kbd{C-x @key{ESC}}, move to the next (more recent) recorded
336 command (@code{next-history-element}).@refill 486 command (@code{next-history-element}).
337 @item M-x list-command-history 487 @item M-x list-command-history
338 Display the entire command history, showing all the commands 488 Display the entire command history, showing all the commands
339 @kbd{C-x @key{ESC}} can repeat, most recent first.@refill 489 @kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first.
340 @end table 490 @end table
341 491
342 @kindex C-x ESC 492 @kindex C-x ESC ESC
343 @findex repeat-complex-command 493 @findex repeat-complex-command
344 @kbd{C-x @key{ESC}} is used to re-execute a recent command that used 494 @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent
345 the minibuffer. With no argument, it repeats the last command. A numeric 495 minibuffer-using command. With no argument, it repeats the last such
346 argument specifies which command to repeat; 1 means the last one, and 496 command. A numeric argument specifies which command to repeat; one
347 larger numbers specify earlier commands. 497 means the last one, and larger numbers specify earlier ones.
348 498
349 @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp 499 @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command
350 expression and then entering a minibuffer initialized with the text for 500 into a Lisp expression and then entering a minibuffer initialized with
351 that expression. If you type just @key{RET}, the command is repeated as 501 the text for that expression. If you type just @key{RET}, the command
352 before. You can also change the command by editing the Lisp expression. 502 is repeated as before. You can also change the command by editing the
353 The expression you finally submit will be executed. The repeated 503 Lisp expression. Whatever expression you finally submit is what will be
354 command is added to the front of the command history unless it is 504 executed. The repeated command is added to the front of the command
355 identical to the most recently executed command already there. 505 history unless it is identical to the most recently executed command
506 already there.
356 507
357 Even if you don't understand Lisp syntax, it will probably be obvious 508 Even if you don't understand Lisp syntax, it will probably be obvious
358 which command is displayed for repetition. If you do not change the text, 509 which command is displayed for repetition. If you do not change the text,
359 you can be sure the command will repeat exactly as before. 510 you can be sure the command will repeat exactly as before.
360 511
361 @kindex M-n 512 @kindex M-n
362 @kindex M-p 513 @kindex M-p
363 @findex next-complex-command 514 @findex next-complex-command
364 @findex previous-complex-command 515 @findex previous-complex-command
365 If you are in the minibuffer for @kbd{C-x @key{ESC}} and the command shown 516 If you are in the minibuffer for @kbd{C-x @key{ESC} @key{ESC}} and the
366 to you is not the one you want to repeat, you can move around the list of 517 command shown to you is not the one you want to repeat, you can move
367 previous commands using @kbd{M-n} and @kbd{M-p}. @kbd{M-p} replaces the 518 around the list of previous commands using @kbd{M-n} and @kbd{M-p}.
368 contents of the minibuffer with the next earlier recorded command, and 519 @kbd{M-p} replaces the contents of the minibuffer with the next earlier
369 @kbd{M-n} replaces it with the next later command. After finding the 520 recorded command, and @kbd{M-n} replaces it with the next later command.
370 desired previous command, you can edit its expression and then 521 After finding the desired previous command, you can edit its expression
371 resubmit it by typing @key{RET}. Any editing you have done on the 522 and then resubmit it by typing @key{RET}. Any editing you have done on
372 command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}. 523 the command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
373 524
374 @kbd{M-n} and @kbd{M-p} are specially defined within @kbd{C-x @key{ESC}} 525 @kbd{M-n} and @kbd{M-p} are specially defined within @kbd{C-x @key{ESC}
375 to run the commands @code{previous-history-element} and 526 @key{ESC}} to run the commands @code{previous-history-element} and
376 @code{next-history-element}. 527 @code{next-history-element}.
377 528
378 @vindex command-history 529 @vindex command-history
379 The list of previous commands using the minibuffer is stored as a Lisp 530 The list of previous commands using the minibuffer is stored as a Lisp
380 list in the variable @code{command-history}. Each element of the list 531 list in the variable @code{command-history}. Each element of the list