Commit | Line | Data |
---|---|---|
3f0faa45 | 1 | \input texinfo @c -*-texinfo-*- |
29993416 | 2 | @setfilename ../../info/ido.info |
3f0faa45 | 3 | @settitle Interactive Do |
c6ab4664 | 4 | @documentencoding UTF-8 |
3f0faa45 XF |
5 | @include emacsver.texi |
6 | ||
7 | @copying | |
8 | This file documents the Ido package for GNU Emacs. | |
9 | ||
ba318903 | 10 | Copyright @copyright{} 2013-2014 Free Software Foundation, Inc. |
3f0faa45 XF |
11 | |
12 | @quotation | |
13 | Permission is granted to copy, distribute and/or modify this document | |
14 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
15 | any later version published by the Free Software Foundation; with no | |
551a89e1 | 16 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
3f0faa45 XF |
17 | and with the Back-Cover Texts as in (a) below. A copy of the license |
18 | is included in the section entitled ``GNU Free Documentation License''. | |
19 | ||
20 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
21 | modify this GNU manual.'' | |
22 | @end quotation | |
23 | @end copying | |
24 | ||
f9405d87 | 25 | @dircategory Emacs misc features |
3f0faa45 | 26 | @direntry |
f9405d87 | 27 | * Ido: (ido). Interactively do things with buffers and files. |
3f0faa45 XF |
28 | @end direntry |
29 | ||
30 | @finalout | |
31 | ||
32 | @titlepage | |
33 | @sp 6 | |
34 | @center @titlefont{Interactive Do} | |
35 | @sp 4 | |
36 | @center For GNU Emacs | |
37 | @sp 1 | |
38 | @center as distributed with Emacs @value{EMACSVER} | |
39 | @sp 5 | |
40 | @center Kim F. Storm | |
41 | @center storm@@cua.dk | |
42 | @page | |
43 | @vskip 0pt plus 1filll | |
44 | @insertcopying | |
45 | @end titlepage | |
46 | ||
47 | @contents | |
48 | ||
49 | @ifnottex | |
50 | @node Top | |
51 | @top Interactive Do | |
52 | ||
53 | @insertcopying | |
54 | @end ifnottex | |
55 | ||
56 | @menu | |
03300a14 XF |
57 | * Overview:: Basics, activation. |
58 | * Matching:: Interactivity, matching, scrolling. | |
59 | * Highlighting:: Highlighting of matching items. | |
60 | * Hidden Buffers and Files:: Hidden buffers, files, and directories. | |
61 | * Customization:: Change the Ido functionality. | |
62 | * Misc:: Various other features. | |
3f0faa45 XF |
63 | |
64 | Appendices | |
03300a14 | 65 | * GNU Free Documentation License:: The license for this documentation. |
3f0faa45 XF |
66 | |
67 | Indexes | |
03300a14 | 68 | * Variable Index:: An entry for each documented variable. |
3f0faa45 XF |
69 | |
70 | @detailmenu | |
71 | --- The Detailed Node Listing --- | |
72 | ||
73 | Overview | |
74 | ||
03300a14 XF |
75 | * Activation:: How to use this package. |
76 | * Working Directories:: Where files have most recently been opened. | |
3f0faa45 XF |
77 | |
78 | Matching | |
79 | ||
03300a14 XF |
80 | * Interactive Substring Matching:: Interactivity, matching, scrolling. |
81 | * Prefix Matching:: Standard completion. | |
82 | * Flexible Matching:: More flexible matching. | |
83 | * Regexp Matching:: Matching using regular expression. | |
3f0faa45 XF |
84 | |
85 | Customization | |
86 | ||
03300a14 XF |
87 | * Changing List Order:: Changing the list of files. |
88 | * Find File At Point:: Make Ido guess the context. | |
89 | * Ignoring:: Ignorance is bliss. | |
90 | * Misc Customization:: Miscellaneous customization for Ido. | |
3f0faa45 XF |
91 | |
92 | Miscellaneous | |
93 | ||
03300a14 XF |
94 | * All Matching:: Seeing all the matching buffers or files. |
95 | * Replacement:: Replacement for @code{read-buffer} and @code{read-file-name}. | |
96 | * Other Packages:: Don't want to depend on @code{ido-everywhere}? | |
3f0faa45 XF |
97 | |
98 | @end detailmenu | |
99 | @end menu | |
100 | ||
101 | @node Overview | |
102 | @chapter Overview | |
103 | @cindex overview | |
104 | ||
105 | @noindent | |
106 | This document describes a set of features that can interactively do | |
107 | things with buffers and files. All the features are described here | |
108 | in detail. | |
109 | ||
110 | The @dfn{Ido} package can let you switch between buffers and visit | |
111 | files and directories with a minimum of keystrokes. It is a superset | |
112 | of Iswitchb, the interactive buffer switching package by Stephen | |
113 | Eglen. | |
114 | ||
115 | @cindex author of Ido | |
116 | @cindex Iswitchb | |
117 | This package was originally written by Kim F. Storm, based on the | |
118 | @file{iswitchb.el} package by Stephen Eglen. | |
119 | ||
120 | @menu | |
03300a14 XF |
121 | * Activation:: How to use this package. |
122 | * Working Directories:: Where files have most recently been opened. | |
3f0faa45 XF |
123 | @end menu |
124 | ||
125 | @node Activation | |
126 | @section Activation | |
127 | @cindex activation | |
128 | @cindex installation | |
129 | ||
130 | @noindent | |
131 | This package is distributed with Emacs, so there is no need to install | |
132 | any additional files in order to start using it. To activate, use | |
133 | @kbd{M-x ido-mode}. | |
134 | ||
135 | @noindent | |
136 | You may wish to add the following expressions to your initialization | |
137 | file (@pxref{Init File,,The Emacs Initialization File, emacs, GNU | |
138 | Emacs Manual}), if you make frequent use of features from this | |
139 | package. | |
140 | ||
141 | @example | |
142 | (require 'ido) | |
143 | (ido-mode t) | |
144 | @end example | |
145 | ||
03300a14 XF |
146 | @node Working Directories |
147 | @section Working Directories | |
148 | @cindex working directories | |
149 | ||
150 | @vindex ido-work-directory-list | |
151 | @noindent | |
152 | @dfn{Working directories} are directories where files have most | |
153 | recently been opened. The current directory is inserted at the front | |
154 | of this @code{ido-work-directory-list} whenever a file is opened with | |
155 | @code{ido-find-file} and other file-related functions. | |
156 | ||
157 | @c @cindex merge | |
158 | @c or maybe a new node for ``merge'' | |
159 | ||
15938cf4 | 160 | @c @deffn Command ido-merge-work-directories |
03300a14 | 161 | |
15938cf4 | 162 | @c @deffn Command ido-prev-work-directory |
03300a14 | 163 | |
15938cf4 | 164 | @c @deffn Command ido-next-work-directory |
03300a14 | 165 | |
15938cf4 | 166 | @c @deffn Command ido-forget-work-directory |
03300a14 | 167 | |
15938cf4 XF |
168 | @c @defvar ido-use-merged-list |
169 | @c @defvar ido-try-merged-list | |
170 | @c @defvar ido-pre-merge-state | |
03300a14 | 171 | |
33a9f380 | 172 | @defopt ido-max-work-directory-list |
03300a14 XF |
173 | This user option specifies maximum number of working directories to |
174 | record. | |
33a9f380 | 175 | @end defopt |
03300a14 XF |
176 | |
177 | @c see (info "(elisp) File Name Completion") | |
33a9f380 | 178 | @defopt ido-max-dir-file-cache |
03300a14 XF |
179 | This user option specifies maximum number of working directories to be |
180 | cached. This is the size of the cache of | |
181 | @code{file-name-all-completions} results. Each cache entry is time | |
182 | stamped with the modification time of the directory. Some systems, | |
183 | like MS-Windows, have unreliable directory modification times, so you | |
184 | may choose to disable caching on such systems, or explicitly refresh | |
185 | the cache contents using the command @code{ido-reread-directory} | |
186 | (usually @kbd{C-l}) in the minibuffer. | |
33a9f380 | 187 | @end defopt |
3f0faa45 XF |
188 | |
189 | @node Matching | |
190 | @chapter Matching | |
191 | @cindex matching | |
192 | ||
193 | @noindent | |
194 | This section describes features of this package that have to | |
195 | do with various kinds of @emph{matching}: among buffers, files, and directories. | |
196 | ||
197 | @menu | |
03300a14 XF |
198 | * Interactive Substring Matching:: Interactivity, matching, scrolling. |
199 | * Prefix Matching:: Standard completion. | |
200 | * Flexible Matching:: More flexible matching. | |
201 | * Regexp Matching:: Matching using regular expression. | |
3f0faa45 XF |
202 | @end menu |
203 | ||
204 | @node Interactive Substring Matching | |
205 | @section Interactive Substring Matching | |
206 | @cindex interactive substring matching | |
207 | @cindex substring, interactive matching | |
208 | @cindex matching, using substring | |
209 | ||
210 | @noindent | |
211 | As you type in a substring, the list of buffers or files currently | |
212 | matching the substring are displayed as you type. The list is | |
213 | ordered so that the most recent buffers or files visited come at | |
214 | the start of the list. | |
215 | ||
216 | The buffer or file at the start of the list will be the one visited | |
217 | when you press @key{RET}. By typing more of the substring, the list | |
218 | is narrowed down so that gradually the buffer or file you want will be | |
219 | at the top of the list. Alternatively, you can use @kbd{C-s} and | |
220 | @kbd{C-r} (or the right and left arrow keys) to rotate buffer or file | |
221 | names in the list until the one you want is at the top of the list. | |
222 | ||
223 | Completion is also available so that you can see what is common to | |
224 | all of the matching buffers or files as you type. | |
225 | ||
226 | For example, if there are two buffers called @file{123456} and | |
227 | @file{123}, with @file{123456} the most recent, when using | |
228 | @code{ido-switch-buffer}, you first of all get presented with the list | |
229 | of all the buffers | |
230 | ||
231 | @example | |
232 | Buffer: @{123456 | 123@} | |
233 | @end example | |
234 | ||
235 | If you then press @kbd{2}: | |
236 | ||
237 | @example | |
238 | Buffer: 2[3]@{123456 | 123@} | |
239 | @end example | |
240 | ||
241 | The list in @{...@} are the matching buffers, most recent first | |
242 | (buffers visible in the current frame are put at the end of the list | |
243 | by default). At any time you can select the item at the head of the | |
244 | list by pressing @key{RET}. You can also put the first element at the | |
245 | end of the list by pressing @kbd{C-s} or @kbd{<right>}, or bring the | |
246 | last element to the head of the list by pressing @kbd{C-r} or | |
247 | @kbd{<left>}. | |
248 | ||
249 | The item in [...] indicates what can be added to your input by | |
250 | pressing @key{TAB} (@code{ido-complete}). In this case, you will get | |
251 | "3" added to your input. | |
252 | ||
253 | So, press @key{TAB}: | |
254 | ||
255 | @example | |
256 | Buffer: 23@{123456 | 123@} | |
257 | @end example | |
258 | ||
259 | At this point, you still have two matching buffers. If you want the | |
260 | first buffer in the list, you can simply press @key{RET}. If you want | |
261 | the second in the list, you can press @kbd{C-s} to move it to the top | |
412a0972 | 262 | of the list and then press @key{RET} to select it. |
3f0faa45 XF |
263 | |
264 | However, if you type @kbd{4}, you'll only have one match left: | |
265 | ||
266 | @example | |
267 | Buffer: 234[123456] | |
268 | @end example | |
269 | ||
270 | Since there is only one matching buffer left, it is given in [] and it | |
271 | is shown in the @code{ido-only-match} face (ForestGreen). You can now | |
272 | press @key{TAB} or @key{RET} to go to that buffer. | |
273 | ||
274 | If you want to create a new buffer named @file{234}, you can press | |
275 | @kbd{C-j} (@code{ido-select-text}) instead of @key{TAB} or @key{RET}. | |
276 | ||
277 | If instead, you type @kbd{a}: | |
278 | ||
279 | @example | |
280 | Buffer: 234a [No match] | |
281 | @end example | |
282 | ||
283 | There are no matching buffers. If you press @key{RET} or @key{TAB}, | |
284 | you can be prompted to create a new buffer called @file{234a}. | |
285 | ||
286 | Of course, where this function comes in really useful is when you can | |
287 | specify the buffer using only a few keystrokes. In the above example, | |
288 | the quickest way to get to the @file{123456} file would be just to | |
289 | type @kbd{4} and then @key{RET} (assuming there isn't any newer buffer | |
290 | with @kbd{4} in its name). | |
291 | ||
292 | Likewise, if you use @kbd{C-x C-f} (@code{ido-find-file}), the list of | |
293 | files and directories in the current directory is provided in the same | |
294 | fashion as the buffers above. The files and directories are normally | |
295 | sorted in alphabetical order, but the most recently visited directory | |
296 | is placed first to speed up navigating to directories that you have | |
297 | visited recently. | |
298 | ||
299 | In addition to scrolling through the list using @kbd{<right>} and | |
300 | @kbd{<left>}, you can use @kbd{<up>} and @kbd{<down>} to quickly | |
301 | scroll the list to the next or previous subdirectory. | |
302 | ||
303 | To go down into a subdirectory, and continue the file selection on | |
304 | the files in that directory, simply move the directory to the head | |
305 | of the list and hit @key{RET}. | |
306 | ||
307 | To go up to the parent directory, delete any partial file name already | |
308 | specified (e.g. using @key{DEL}) and hit @key{DEL}. | |
309 | ||
15938cf4 | 310 | @c @deffn Command ido-delete-backward-updir |
3f0faa45 XF |
311 | |
312 | @cindex root directory | |
313 | @cindex home directory | |
314 | To go to the root directory (on the current drive), enter two slashes. | |
315 | On MS-DOS or Windows, to select the root of another drive, enter | |
316 | @samp{X:/} where @samp{X} is the drive letter. To go to the home | |
317 | directory, enter @samp{~/}. To enter Dired for this directory, use | |
94fea300 | 318 | @kbd{C-d}. |
3f0faa45 XF |
319 | |
320 | @c TODO: a new node for ftp hosts | |
321 | @cindex ftp hosts | |
322 | You can also visit files on other hosts using the ange-ftp | |
323 | notations @samp{/host:} and @samp{/user@@host:}. | |
33a9f380 XF |
324 | @c @defopt ido-record-ftp-work-directories |
325 | @c @defopt ido-merge-ftp-work-directories | |
326 | @c @defopt ido-cache-ftp-work-directory-time | |
327 | @c @defopt ido-slow-ftp-hosts | |
328 | @c @defopt ido-slow-ftp-host-regexps | |
3f0faa45 XF |
329 | |
330 | You can type @kbd{M-p} and @kbd{M-n} to change to previous/next | |
331 | directories from the history, @kbd{M-s} to search for a file matching | |
332 | your input, and @kbd{M-k} to remove the current directory from the history. | |
333 | ||
334 | If for some reason you cannot specify the proper file using | |
335 | @code{ido-find-file}, you can press @kbd{C-f} to enter the normal | |
336 | @code{find-file}. You can also press @kbd{C-b} to drop into | |
337 | @code{ido-switch-buffer}. | |
338 | ||
339 | @c @kindex C-x b | |
15938cf4 | 340 | @c @deffn Command ido-switch-buffer |
3f0faa45 | 341 | @c This command switch to another buffer interactively. |
15938cf4 | 342 | @c @end deffn |
3f0faa45 XF |
343 | |
344 | @c @kindex C-x C-f | |
15938cf4 | 345 | @c @deffn Command ido-find-file |
3f0faa45 | 346 | @c Edit file with name obtained via minibuffer. |
15938cf4 | 347 | @c @end deffn |
3f0faa45 XF |
348 | |
349 | @c @kindex C-x d | |
350 | @c @findex ido-dired | |
15938cf4 | 351 | @c @deffn Command ido-dired |
3f0faa45 | 352 | @c Call Dired the Ido way. |
15938cf4 | 353 | @c @end deffn |
3f0faa45 XF |
354 | |
355 | @node Prefix Matching | |
356 | @section Prefix Matching | |
357 | @cindex prefix matching | |
358 | @cindex matching, using prefix | |
359 | @cindex standard way of completion | |
360 | ||
361 | @noindent | |
362 | The standard way of completion with *nix shells and Emacs is to insert | |
363 | a @dfn{prefix} and then hitting @key{TAB} (or another completion key). | |
364 | Cause of this behavior has become second nature to a lot of Emacs | |
365 | users Ido offers in addition to the default substring matching method | |
366 | (look above) also the prefix matching method. The kind of matching is | |
367 | the only difference to the description of the substring matching | |
368 | above. | |
369 | ||
412a0972 | 370 | @cindex toggle prefix matching |
3f0faa45 XF |
371 | You can toggle prefix matching with @kbd{C-p} |
372 | (@code{ido-toggle-prefix}). | |
373 | ||
374 | For example, if you have two buffers @file{123456} and @file{123} then | |
375 | hitting @kbd{2} does not match because @kbd{2} is not a prefix in any | |
376 | of the buffer names. | |
377 | ||
378 | @node Flexible Matching | |
379 | @section Flexible Matching | |
380 | @cindex flexible matching | |
381 | ||
33a9f380 | 382 | @defopt ido-enable-flex-matching |
3f0faa45 XF |
383 | If non-@code{nil}, Ido will do flexible string matching. Flexible |
384 | matching means that if the entered string does not match any item, any | |
385 | item containing the entered characters in the given sequence will | |
386 | match. | |
33a9f380 | 387 | @end defopt |
3f0faa45 XF |
388 | |
389 | @noindent | |
390 | If @code{ido-enable-flex-matching} is non-@code{nil}, Ido will do a | |
391 | more flexible matching (unless regexp matching is active) to find | |
392 | possible matches among the available buffer or file names if no | |
393 | matches are found using the normal prefix or substring matching. | |
394 | ||
395 | The flexible matching implies that any item which simply contains all | |
396 | of the entered characters in the specified sequence will match. | |
397 | ||
398 | For example, if you have four files @file{alpha}, @file{beta}, | |
399 | @file{gamma}, and @file{delta}, entering @samp{aa} will match | |
400 | @file{alpha} and @file{gamma}, while @samp{ea} matches @file{beta} and | |
401 | @file{delta}. If prefix matching is also active, @samp{aa} only | |
402 | matches @file{alpha}, while @samp{ea} does not match any files. | |
403 | ||
404 | @node Regexp Matching | |
405 | @section Regular Expression Matching | |
406 | @cindex regexp matching | |
407 | @cindex matching, using regular expression | |
408 | ||
409 | @noindent | |
410 | There is limited provision for regexp matching within Ido, enabled | |
411 | through @code{ido-enable-regexp} (toggle with @kbd{C-t}). This allows | |
412 | you to type @samp{[ch]$} for example and see all file names ending in | |
413 | @samp{c} or @samp{h}. | |
414 | ||
33a9f380 | 415 | @defopt ido-enable-regexp |
3f0faa45 XF |
416 | If the value of this user option is non-@code{nil}, Ido will do regexp |
417 | matching. The value of this user option can be toggled within | |
418 | ido-mode using @code{ido-toggle-regexp}. | |
33a9f380 | 419 | @end defopt |
3f0faa45 XF |
420 | |
421 | @strong{Please notice:} Ido-style completion is inhibited when you | |
422 | enable regexp matching. | |
423 | ||
424 | @node Highlighting | |
425 | @chapter Highlighting | |
426 | @cindex highlighting | |
427 | ||
428 | @noindent | |
429 | The highlighting of matching items is controlled via | |
430 | @code{ido-use-faces}. The faces used are @code{ido-first-match}, | |
431 | @code{ido-only-match} and @code{ido-subdir}. | |
432 | ||
433 | Coloring of the matching item was suggested by Carsten Dominik. | |
434 | ||
435 | @node Hidden Buffers and Files | |
436 | @chapter Hidden Buffers and Files | |
437 | @cindex hidden buffers and files | |
438 | ||
439 | Normally, Ido does not include hidden buffers (whose name starts with | |
440 | a space) and hidden files and directories (whose name starts with | |
441 | @samp{.}) in the list of possible completions. However, if the | |
442 | substring you enter does not match any of the visible buffers or | |
443 | files, Ido will automatically look for completions among the hidden | |
444 | buffers or files. | |
445 | ||
446 | You can toggle display of the hidden buffers and files with @kbd{C-a} | |
447 | (@code{ido-toggle-ignore}). | |
448 | ||
15938cf4 | 449 | @c @deffn Command ido-toggle-ignore |
3f0faa45 XF |
450 | |
451 | @node Customization | |
452 | @chapter Customization | |
453 | @cindex customization | |
454 | ||
455 | @noindent | |
456 | You can customize the @code{ido} group to change Ido functionality: | |
457 | ||
458 | @example | |
459 | M-x customize-group RET ido RET | |
460 | @end example | |
461 | ||
462 | @noindent | |
463 | or customize a certain variable: | |
464 | ||
465 | @example | |
466 | M-x customize-variable RET ido-xxxxx | |
467 | @end example | |
468 | ||
469 | To modify the keybindings, use the @code{ido-setup-hook}. For example: | |
470 | ||
471 | @example | |
472 | (add-hook 'ido-setup-hook 'ido-my-keys) | |
473 | ||
474 | (defun ido-my-keys () | |
475 | "Add my keybindings for Ido." | |
476 | (define-key ido-completion-map " " 'ido-next-match)) | |
477 | @end example | |
478 | ||
33a9f380 | 479 | @c @defopt ido-setup-hook |
919a9575 XF |
480 | @c a new node for Ido hooks? |
481 | ||
3f0faa45 XF |
482 | @menu |
483 | * Changing List Order:: Changing the list of files. | |
484 | * Find File At Point:: Make Ido guess the context. | |
485 | * Ignoring:: Ignorance is bliss. | |
486 | * Misc Customization:: Miscellaneous customization for Ido. | |
487 | @end menu | |
488 | ||
489 | @node Changing List Order | |
490 | @section Changing List Order | |
491 | @cindex changing order of the list | |
492 | ||
493 | @noindent | |
494 | By default, the list of current files is most recent first, | |
495 | oldest last, with the exception that the files visible in the | |
496 | current frame are put at the end of the list. A hook exists to | |
497 | allow other functions to order the list. For example, if you add: | |
498 | ||
499 | @example | |
500 | (add-hook 'ido-make-buffer-list-hook 'ido-summary-buffers-to-end) | |
501 | @end example | |
502 | ||
503 | @noindent | |
504 | then all files matching "Summary" are moved to the end of the list. | |
505 | (I find this handy for keeping the INBOX Summary and so on out of the | |
506 | way.) It also moves files matching @samp{output\*$} to the end of the | |
507 | list (these are created by AUCTeX when compiling.) Other functions | |
508 | could be made available which alter the list of matching files (either | |
509 | deleting or rearranging elements.) | |
510 | ||
511 | @node Find File At Point | |
512 | @section Find File At Point | |
513 | @cindex find file at point | |
514 | @cindex ffap | |
515 | ||
516 | @noindent | |
517 | Find File At Point, also known generally as ``ffap'', is an | |
518 | intelligent system for opening files, and URLs. | |
519 | ||
520 | The following expression will make Ido guess the context: | |
521 | ||
522 | @example | |
523 | (setq ido-use-filename-at-point 'guess) | |
524 | @end example | |
525 | ||
33a9f380 | 526 | @c @defopt ido-use-filename-at-point |
3f0faa45 | 527 | @c If the value of this user option is non-@code{nil}, ... |
33a9f380 | 528 | @c @end defopt |
3f0faa45 XF |
529 | |
530 | You can disable URL ffap support by toggling | |
531 | @code{ido-use-url-at-point}. | |
532 | ||
33a9f380 | 533 | @defopt ido-use-url-at-point |
3f0faa45 XF |
534 | If the value of this user option is non-@code{nil}, Ido will look for |
535 | a URL at point. If found, call @code{find-file-at-point} to visit it. | |
33a9f380 | 536 | @end defopt |
3f0faa45 XF |
537 | |
538 | @node Ignoring | |
539 | @section Ignoring Buffers and Files | |
540 | @cindex ignoring | |
541 | @cindex regexp, ignore buffers and files | |
542 | ||
543 | @noindent | |
544 | Ido is capable of ignoring buffers, directories, files and extensions | |
545 | using regular expression. | |
546 | ||
33a9f380 | 547 | @defopt ido-ignore-buffers |
3f0faa45 XF |
548 | This variable takes a list of regular expressions for buffers to |
549 | ignore in @code{ido-switch-buffer}. | |
33a9f380 | 550 | @end defopt |
3f0faa45 | 551 | |
33a9f380 | 552 | @defopt ido-ignore-directories |
3f0faa45 XF |
553 | This variable takes a list of regular expressions for (sub)directories |
554 | names to ignore in @code{ido-dired} and @code{ido-find-file}. | |
33a9f380 | 555 | @end defopt |
3f0faa45 | 556 | |
33a9f380 | 557 | @defopt ido-ignore-files |
3f0faa45 XF |
558 | This variable takes a list of regular expressions for files to ignore |
559 | in @code{ido-find-file}. | |
33a9f380 | 560 | @end defopt |
3f0faa45 | 561 | |
33a9f380 | 562 | @defopt ido-ignore-unc-host-regexps |
3f0faa45 XF |
563 | This variable takes a list of regular expressions matching UNC hosts |
564 | to ignore. The letter case will be ignored if | |
565 | @code{ido-downcase-unc-hosts} is non-@code{nil}. | |
33a9f380 | 566 | @end defopt |
3f0faa45 | 567 | |
03300a14 | 568 | @c FIXME: Where to add this variable? This node or ``working directory''? |
33a9f380 | 569 | @c @defopt ido-work-directory-list-ignore-regexps |
3f0faa45 XF |
570 | |
571 | To make Ido use @code{completion-ignored-extensions} you need to | |
572 | enable it: | |
573 | ||
574 | @example | |
575 | (setq ido-ignore-extensions t) | |
576 | @end example | |
577 | ||
578 | Now you can customize @code{completion-ignored-extensions} as well. | |
579 | Go ahead and add all the useless object files, backup files, shared | |
b483c570 | 580 | library files and other computing flotsam you don't want Ido to show. |
3f0faa45 XF |
581 | |
582 | @strong{Please notice:} Ido will still complete the ignored elements | |
583 | if it would otherwise not show any other matches. So if you type out | |
584 | the name of an ignored file, Ido will still let you open it just fine. | |
585 | ||
586 | @node Misc Customization | |
587 | @section Miscellaneous Customization | |
588 | @cindex miscellaneous customization for Ido | |
589 | ||
9dfc8491 XF |
590 | @c Variables described in this sections may be moved to new nodes in |
591 | @c the future. | |
592 | ||
33a9f380 | 593 | @defopt ido-mode |
3f0faa45 XF |
594 | This user option determines for which functional group (buffer and |
595 | files) Ido behavior should be enabled. | |
33a9f380 | 596 | @end defopt |
3f0faa45 | 597 | |
33a9f380 | 598 | @defopt ido-case-fold |
3f0faa45 XF |
599 | If the value of this user option is non-@code{nil}, searching of |
600 | buffer and file names should ignore case. | |
33a9f380 | 601 | @end defopt |
3f0faa45 | 602 | |
33a9f380 | 603 | @defopt ido-show-dot-for-dired |
15938cf4 | 604 | If the value of this user option is non-@code{nil}, always put |
3f0faa45 XF |
605 | @samp{.} as the first item in file name lists. This allows the |
606 | current directory to be opened immediately with Dired | |
33a9f380 | 607 | @end defopt |
3f0faa45 | 608 | |
33a9f380 | 609 | @defopt ido-enable-dot-prefix |
3f0faa45 XF |
610 | If the value of this user option is non-@code{nil}, Ido will match |
611 | leading dot as prefix. I.e., hidden files and buffers will match only | |
612 | if you type a dot as first char (even if @code{ido-enable-prefix} is | |
613 | @code{nil}). | |
33a9f380 | 614 | @end defopt |
3f0faa45 | 615 | |
33a9f380 | 616 | @defopt ido-confirm-unique-completion |
9dfc8491 | 617 | If the value of this user option is non-@code{nil}, even a unique |
15938cf4 XF |
618 | completion must be confirmed. This means that @code{ido-complete} |
619 | (@key{TAB}) must always be followed by @code{ido-exit-minibuffer} | |
620 | (@key{RET}) even when there is only one unique completion. | |
33a9f380 | 621 | @end defopt |
15938cf4 | 622 | |
33a9f380 | 623 | @defopt ido-cannot-complete-command |
9dfc8491 XF |
624 | When @code{ido-complete} can't complete any more, it will run the |
625 | command specified by this user option. The most useful values are | |
626 | @code{ido-completion-help}, which pops up a window with completion | |
627 | alternatives, or @code{ido-next-match} or @code{ido-prev-match}, which | |
628 | cycle the buffer list. | |
33a9f380 | 629 | @end defopt |
9dfc8491 | 630 | |
33a9f380 | 631 | @defopt ido-max-file-prompt-width |
9dfc8491 XF |
632 | This user option specifies the upper limit of the prompt string. If |
633 | its value is an integer, it specifies the number of characters of the | |
634 | string. If its value is a floating point number, it specifies a | |
635 | fraction of the frame width. | |
33a9f380 | 636 | @end defopt |
9dfc8491 | 637 | |
33a9f380 | 638 | @defopt ido-max-window-height |
04263d23 | 639 | If the value of this user option is non-@code{nil}, its value will |
9dfc8491 XF |
640 | override the variable @code{max-mini-window-height}, which is the |
641 | maximum height for resizing mini-windows (the minibuffer and the echo | |
642 | area). If it's a floating point number, it specifies a fraction of | |
643 | the mini-window frame's height. If it's an integer, it specifies the | |
644 | number of lines. | |
33a9f380 | 645 | @end defopt |
9dfc8491 | 646 | |
33a9f380 | 647 | @defopt ido-record-commands |
04263d23 XF |
648 | If the value of this user option is non-@code{nil}, Ido will record |
649 | commands in the variable @code{command-history}. Note that non-Ido | |
650 | equivalent is recorded. | |
33a9f380 | 651 | @end defopt |
04263d23 | 652 | |
33a9f380 | 653 | @defopt ido-all-frames |
919a9575 XF |
654 | This user option will be passed to @code{walk-windows} as its |
655 | @var{all-frames} argument when Ido is finding buffers. @xref{Cyclic | |
656 | Window Ordering, , Cyclic Ordering of Windows, elisp, GNU Emacs Lisp | |
657 | Reference Manual}. | |
33a9f380 | 658 | @end defopt |
919a9575 | 659 | |
33a9f380 | 660 | @defopt ido-minibuffer-setup-hook |
919a9575 XF |
661 | This hook variable contains Ido-specific customization of minibuffer |
662 | setup. It is run during minibuffer setup if Ido is active, and is | |
663 | intended for use in customizing ido for interoperation with other | |
664 | packages. | |
33a9f380 | 665 | @end defopt |
919a9575 | 666 | |
33a9f380 | 667 | @c @defopt ido-enable-tramp-completion |
919a9575 XF |
668 | @c cross-reference to tramp.texi |
669 | ||
670 | @c @cindex UNC host names, completion | |
33a9f380 XF |
671 | @c @defopt ido-unc-hosts |
672 | @c @defopt ido-downcase-unc-hosts | |
673 | @c @defopt ido-cache-unc-host-shares-time | |
674 | ||
675 | @c @defopt ido-enable-last-directory-history | |
676 | @c @defopt ido-max-work-file-list | |
677 | @c @defopt ido-work-directory-match-only | |
678 | @c @defopt ido-auto-merge-work-directories-length | |
679 | @c @defopt ido-auto-merge-delay-time | |
680 | @c @defopt ido-auto-merge-inhibit-characters-regexp | |
681 | @c @defopt ido-merged-indicator | |
682 | @c @defopt ido-max-directory-size | |
683 | @c @defopt ido-rotate-file-list-default | |
684 | @c @defopt ido-enter-matching-directory | |
685 | @c @defopt ido-create-new-buffer | |
686 | @c @defopt ido-separator | |
687 | @c @defopt ido-decorations | |
688 | @c @defopt ido-use-virtual-buffers | |
689 | @c @defopt ido-use-faces | |
690 | @c @defopt ido-make-file-list-hook | |
691 | @c @defopt ido-make-dir-list-hook | |
692 | @c @defopt ido-make-buffer-list-hook | |
693 | @c @defopt ido-rewrite-file-prompt-functions | |
694 | @c @defopt ido-completion-buffer | |
695 | @c @defopt ido-completion-buffer-all-completions | |
696 | @c @defopt ido-save-directory-list-file | |
697 | @c @defopt ido-read-file-name-as-directory-commands | |
698 | @c @defopt ido-read-file-name-non-ido | |
699 | @c @defopt ido-before-fallback-functions | |
700 | @c @defopt ido-buffer-disable-smart-matches | |
3f0faa45 XF |
701 | |
702 | @node Misc | |
703 | @chapter Miscellaneous | |
704 | @cindex miscellaneous | |
705 | ||
706 | @noindent | |
707 | After @kbd{C-x b} (@code{ido-switch-buffer}), the buffer at the head | |
708 | of the list can be killed by pressing @kbd{C-k}. If the buffer needs | |
709 | saving, you will be queried before the buffer is killed. | |
710 | ||
711 | Likewise, after @kbd{C-x C-f}, you can delete (i.e., physically | |
712 | remove) the file at the head of the list with @kbd{C-k}. You will | |
713 | always be asked for confirmation before deleting the file. | |
714 | ||
715 | If you enter @kbd{C-x b} to switch to a buffer visiting a given file, | |
716 | and you find that the file you are after is not in any buffer, you can | |
717 | press @kbd{C-f} to immediately drop into @code{ido-find-file}. And | |
718 | you can switch back to buffer selection with @kbd{C-b}. | |
719 | ||
15938cf4 XF |
720 | @c @deffn Command ido-magic-forward-char |
721 | @c @deffn Command ido-magic-backward-char | |
3f0faa45 XF |
722 | |
723 | You can also use Ido in your Emacs Lisp programs: | |
724 | ||
725 | @example | |
726 | (setq my-pkgs (list "CEDET" "Gnus" "Rcirc" "Tramp" "Org" "all-of-them")) | |
727 | (ido-completing-read "What's your favorite package? " my-pkgs) | |
728 | @end example | |
729 | ||
730 | @menu | |
731 | * All Matching:: Seeing all the matching buffers or files. | |
732 | * Replacement:: Replacement for @code{read-buffer} and @code{read-file-name}. | |
733 | * Other Packages:: Don't want to depend on @code{ido-everywhere}? | |
734 | @end menu | |
735 | ||
736 | @node All Matching | |
737 | @section All Matching | |
738 | @cindex all matching | |
739 | @cindex seeing all the matching buffers or files | |
740 | ||
741 | @noindent | |
742 | If you have many matching files, they may not all fit onto one line of | |
743 | the minibuffer. Normally, the minibuffer window will grow to show you | |
744 | more of the matching files (depending on the value of the variables | |
745 | @code{resize-mini-windows} and @code{max-mini-window-height}). If you | |
746 | want Ido to behave differently from the default minibuffer resizing | |
747 | behavior, set the variable @code{ido-max-window-height}. | |
748 | ||
749 | Also, to improve the responsiveness of Ido, the maximum number of | |
750 | matching items is limited to 12, but you can increase or removed this | |
751 | limit via the @code{ido-max-prospects} user option. | |
752 | ||
33a9f380 | 753 | @c @defopt ido-max-prospects |
3f0faa45 XF |
754 | |
755 | To see a full list of all matching buffers in a separate buffer, hit | |
756 | @kbd{?} or press @key{TAB} when there are no further completions to | |
757 | the substring. Repeated @key{TAB} presses will scroll you through | |
758 | this separate buffer. | |
759 | ||
760 | @node Replacement | |
761 | @section Replacement | |
762 | ||
763 | @noindent | |
764 | @code{ido-read-buffer} and @code{ido-read-file-name} have been written | |
765 | to be drop in replacements for the normal buffer and file name reading | |
766 | functions @code{read-buffer} and @code{read-file-name}. | |
767 | ||
768 | To use ido for all buffer and file selections in Emacs, customize the | |
769 | variable @code{ido-everywhere}. | |
770 | ||
15938cf4 | 771 | @c @deffn Command ido-everywhere |
33a9f380 | 772 | @c @defopt ido-everywhere |
3f0faa45 XF |
773 | |
774 | @node Other Packages | |
775 | @section Other Packages | |
776 | @cindex other packages | |
777 | @cindex used by other packages | |
778 | ||
779 | @noindent | |
780 | If you don't want to rely on the @code{ido-everywhere} functionality, | |
781 | @code{ido-read-buffer}, @code{ido-read-file-name}, and | |
782 | @code{ido-read-directory-name} can be used by other packages to read a | |
783 | buffer name, a file name, or a directory name in the @emph{Ido} way. | |
784 | ||
94fea300 | 785 | @c @node Cheatsheet |
3f0faa45 XF |
786 | |
787 | @c * History and Acknowledgments:: How Ido came into being | |
788 | @c @node History and Acknowledgments | |
789 | @c @appendix History and Acknowledgments | |
790 | ||
791 | @node GNU Free Documentation License | |
792 | @appendix GNU Free Documentation License | |
793 | @include doclicense.texi | |
794 | ||
795 | @c @node Function Index | |
796 | @c @unnumbered Function Index | |
797 | ||
798 | @c @printindex fn | |
799 | ||
800 | @node Variable Index | |
801 | @unnumbered Variable Index | |
802 | ||
803 | @printindex vr | |
804 | ||
805 | @bye |