diff options
Diffstat (limited to 'doc/misc/ido.texi')
| -rw-r--r-- | doc/misc/ido.texi | 712 |
1 files changed, 712 insertions, 0 deletions
diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi new file mode 100644 index 00000000000..e61a90463c5 --- /dev/null +++ b/doc/misc/ido.texi @@ -0,0 +1,712 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../../info/ido +@settitle Interactive Do +@include emacsver.texi + +@copying +This file documents the Ido package for GNU Emacs. + +Copyright @copyright{} 2013 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs lisp libraries +@direntry +* Ido: (ido). Interactively do things with buffers and files. +@end direntry + +@finalout + +@titlepage +@sp 6 +@center @titlefont{Interactive Do} +@sp 4 +@center For GNU Emacs +@sp 1 +@center as distributed with Emacs @value{EMACSVER} +@sp 5 +@center Kim F. Storm +@center storm@@cua.dk +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Interactive Do + +@insertcopying +@end ifnottex + +@menu +* Overview:: Basics, activation. +* Matching:: Interactivity, matching, scrolling. +* Highlighting:: Highlighting of matching items. +* Hidden Buffers and Files:: Hidden buffers, files, and directories. +* Customization:: Change the Ido functionality. +* Misc:: Various other features. + +Appendices +* GNU Free Documentation License:: The license for this documentation. + +Indexes +* Variable Index:: An entry for each documented variable. + +@detailmenu + --- The Detailed Node Listing --- + +Overview + +* Activation:: How to use this package. + +Matching + +* Interactive Substring Matching:: Interactivity, matching, scrolling. +* Prefix Matching:: Standard completion. +* Flexible Matching:: More flexible matching. +* Regexp Matching:: Matching using regular expression. + +Customization + +* Changing List Order:: Changing the list of files. +* Find File At Point:: Make Ido guess the context. +* Ignoring:: Ignorance is bliss. +* Misc Customization:: Miscellaneous customization for Ido. + +Miscellaneous + +* All Matching:: Seeing all the matching buffers or files. +* Replacement:: Replacement for @code{read-buffer} and @code{read-file-name}. +* Other Packages:: Don't want to depend on @code{ido-everywhere}? + +@end detailmenu +@end menu + +@node Overview +@chapter Overview +@cindex overview + +@noindent +This document describes a set of features that can interactively do +things with buffers and files. All the features are described here +in detail. + +The @dfn{Ido} package can let you switch between buffers and visit +files and directories with a minimum of keystrokes. It is a superset +of Iswitchb, the interactive buffer switching package by Stephen +Eglen. + +@cindex author of Ido +@cindex Iswitchb +This package was originally written by Kim F. Storm, based on the + @file{iswitchb.el} package by Stephen Eglen. + +@menu +* Activation:: How to use this package. +@end menu + +@node Activation +@section Activation +@cindex activation +@cindex installation + +@noindent +This package is distributed with Emacs, so there is no need to install +any additional files in order to start using it. To activate, use +@kbd{M-x ido-mode}. + +@noindent +You may wish to add the following expressions to your initialization +file (@pxref{Init File,,The Emacs Initialization File, emacs, GNU +Emacs Manual}), if you make frequent use of features from this +package. + +@example +(require 'ido) +(ido-mode t) +@end example + +@c @node Working Directories +@c @section Working Directories +@c @cindex working directories + +@node Matching +@chapter Matching +@cindex matching + +@noindent +This section describes features of this package that have to +do with various kinds of @emph{matching}: among buffers, files, and directories. + +@menu +* Interactive Substring Matching:: Interactivity, matching, scrolling. +* Prefix Matching:: Standard completion. +* Flexible Matching:: More flexible matching. +* Regexp Matching:: Matching using regular expression. +@end menu + +@node Interactive Substring Matching +@section Interactive Substring Matching +@cindex interactive substring matching +@cindex substring, interactive matching +@cindex matching, using substring + +@noindent +As you type in a substring, the list of buffers or files currently +matching the substring are displayed as you type. The list is +ordered so that the most recent buffers or files visited come at +the start of the list. + +The buffer or file at the start of the list will be the one visited +when you press @key{RET}. By typing more of the substring, the list +is narrowed down so that gradually the buffer or file you want will be +at the top of the list. Alternatively, you can use @kbd{C-s} and +@kbd{C-r} (or the right and left arrow keys) to rotate buffer or file +names in the list until the one you want is at the top of the list. + +Completion is also available so that you can see what is common to +all of the matching buffers or files as you type. + +For example, if there are two buffers called @file{123456} and +@file{123}, with @file{123456} the most recent, when using +@code{ido-switch-buffer}, you first of all get presented with the list +of all the buffers + +@example +Buffer: @{123456 | 123@} +@end example + +If you then press @kbd{2}: + +@example +Buffer: 2[3]@{123456 | 123@} +@end example + +The list in @{...@} are the matching buffers, most recent first +(buffers visible in the current frame are put at the end of the list +by default). At any time you can select the item at the head of the +list by pressing @key{RET}. You can also put the first element at the +end of the list by pressing @kbd{C-s} or @kbd{<right>}, or bring the +last element to the head of the list by pressing @kbd{C-r} or +@kbd{<left>}. + +The item in [...] indicates what can be added to your input by +pressing @key{TAB} (@code{ido-complete}). In this case, you will get +"3" added to your input. + +So, press @key{TAB}: + +@example +Buffer: 23@{123456 | 123@} +@end example + +At this point, you still have two matching buffers. If you want the +first buffer in the list, you can simply press @key{RET}. If you want +the second in the list, you can press @kbd{C-s} to move it to the top +of the list and then press @kbd{RET} to select it. + +However, if you type @kbd{4}, you'll only have one match left: + +@example +Buffer: 234[123456] +@end example + +Since there is only one matching buffer left, it is given in [] and it +is shown in the @code{ido-only-match} face (ForestGreen). You can now +press @key{TAB} or @key{RET} to go to that buffer. + +If you want to create a new buffer named @file{234}, you can press +@kbd{C-j} (@code{ido-select-text}) instead of @key{TAB} or @key{RET}. + +If instead, you type @kbd{a}: + +@example +Buffer: 234a [No match] +@end example + +There are no matching buffers. If you press @key{RET} or @key{TAB}, +you can be prompted to create a new buffer called @file{234a}. + +Of course, where this function comes in really useful is when you can +specify the buffer using only a few keystrokes. In the above example, +the quickest way to get to the @file{123456} file would be just to +type @kbd{4} and then @key{RET} (assuming there isn't any newer buffer +with @kbd{4} in its name). + +Likewise, if you use @kbd{C-x C-f} (@code{ido-find-file}), the list of +files and directories in the current directory is provided in the same +fashion as the buffers above. The files and directories are normally +sorted in alphabetical order, but the most recently visited directory +is placed first to speed up navigating to directories that you have +visited recently. + +In addition to scrolling through the list using @kbd{<right>} and +@kbd{<left>}, you can use @kbd{<up>} and @kbd{<down>} to quickly +scroll the list to the next or previous subdirectory. + +To go down into a subdirectory, and continue the file selection on +the files in that directory, simply move the directory to the head +of the list and hit @key{RET}. + +To go up to the parent directory, delete any partial file name already +specified (e.g. using @key{DEL}) and hit @key{DEL}. + +@c @defun ido-delete-backward-updir + +@cindex root directory +@cindex home directory +To go to the root directory (on the current drive), enter two slashes. +On MS-DOS or Windows, to select the root of another drive, enter +@samp{X:/} where @samp{X} is the drive letter. To go to the home +directory, enter @samp{~/}. To enter Dired for this directory, use +@kbd{C-d}. + +@c TODO: a new node for ftp hosts +@cindex ftp hosts +You can also visit files on other hosts using the ange-ftp +notations @samp{/host:} and @samp{/user@@host:}. +@c @defvr {User Option} ido-record-ftp-work-directories +@c @defvr {User Option} ido-merge-ftp-work-directories +@c @defvr {User Option} ido-cache-ftp-work-directory-time +@c @defvr {User Option} ido-slow-ftp-hosts +@c @defvr {User Option} ido-slow-ftp-host-regexps + +You can type @kbd{M-p} and @kbd{M-n} to change to previous/next +directories from the history, @kbd{M-s} to search for a file matching +your input, and @kbd{M-k} to remove the current directory from the history. + +If for some reason you cannot specify the proper file using +@code{ido-find-file}, you can press @kbd{C-f} to enter the normal +@code{find-file}. You can also press @kbd{C-b} to drop into +@code{ido-switch-buffer}. + +@c @kindex C-x b +@c @findex ido-switch-buffer +@c @defun ido-switch-buffer +@c This command switch to another buffer interactively. +@c @end defun + +@c @kindex C-x C-f +@c @findex ido-find-file +@c @defun ido-find-file +@c Edit file with name obtained via minibuffer. +@c @end defun + +@c @kindex C-x d +@c @findex ido-dired +@c @defun ido-dired +@c Call Dired the Ido way. +@c @end defun + +@node Prefix Matching +@section Prefix Matching +@cindex prefix matching +@cindex matching, using prefix +@cindex standard way of completion + +@noindent +The standard way of completion with *nix shells and Emacs is to insert +a @dfn{prefix} and then hitting @key{TAB} (or another completion key). +Cause of this behavior has become second nature to a lot of Emacs +users Ido offers in addition to the default substring matching method +(look above) also the prefix matching method. The kind of matching is +the only difference to the description of the substring matching +above. + +You can toggle prefix matching with @kbd{C-p} +(@code{ido-toggle-prefix}). + +For example, if you have two buffers @file{123456} and @file{123} then +hitting @kbd{2} does not match because @kbd{2} is not a prefix in any +of the buffer names. + +@node Flexible Matching +@section Flexible Matching +@cindex flexible matching + +@defvr {User Option} ido-enable-flex-matching +If non-@code{nil}, Ido will do flexible string matching. Flexible +matching means that if the entered string does not match any item, any +item containing the entered characters in the given sequence will +match. +@end defvr + +@noindent +If @code{ido-enable-flex-matching} is non-@code{nil}, Ido will do a +more flexible matching (unless regexp matching is active) to find +possible matches among the available buffer or file names if no +matches are found using the normal prefix or substring matching. + +The flexible matching implies that any item which simply contains all +of the entered characters in the specified sequence will match. + +For example, if you have four files @file{alpha}, @file{beta}, +@file{gamma}, and @file{delta}, entering @samp{aa} will match +@file{alpha} and @file{gamma}, while @samp{ea} matches @file{beta} and +@file{delta}. If prefix matching is also active, @samp{aa} only +matches @file{alpha}, while @samp{ea} does not match any files. + +@node Regexp Matching +@section Regular Expression Matching +@cindex regexp matching +@cindex matching, using regular expression + +@noindent +There is limited provision for regexp matching within Ido, enabled +through @code{ido-enable-regexp} (toggle with @kbd{C-t}). This allows +you to type @samp{[ch]$} for example and see all file names ending in +@samp{c} or @samp{h}. + +@defvr {User Option} ido-enable-regexp +If the value of this user option is non-@code{nil}, Ido will do regexp +matching. The value of this user option can be toggled within +ido-mode using @code{ido-toggle-regexp}. +@end defvr + +@strong{Please notice:} Ido-style completion is inhibited when you +enable regexp matching. + +@node Highlighting +@chapter Highlighting +@cindex highlighting + +@noindent +The highlighting of matching items is controlled via +@code{ido-use-faces}. The faces used are @code{ido-first-match}, +@code{ido-only-match} and @code{ido-subdir}. + +Coloring of the matching item was suggested by Carsten Dominik. + +@node Hidden Buffers and Files +@chapter Hidden Buffers and Files +@cindex hidden buffers and files + +Normally, Ido does not include hidden buffers (whose name starts with +a space) and hidden files and directories (whose name starts with +@samp{.}) in the list of possible completions. However, if the +substring you enter does not match any of the visible buffers or +files, Ido will automatically look for completions among the hidden +buffers or files. + +You can toggle display of the hidden buffers and files with @kbd{C-a} +(@code{ido-toggle-ignore}). + +@c @defun ido-toggle-ignore + +@node Customization +@chapter Customization +@cindex customization + +@noindent +You can customize the @code{ido} group to change Ido functionality: + +@example +M-x customize-group RET ido RET +@end example + +@noindent +or customize a certain variable: + +@example +M-x customize-variable RET ido-xxxxx +@end example + +To modify the keybindings, use the @code{ido-setup-hook}. For example: + +@example +(add-hook 'ido-setup-hook 'ido-my-keys) + +(defun ido-my-keys () + "Add my keybindings for Ido." + (define-key ido-completion-map " " 'ido-next-match)) +@end example + +@menu +* Changing List Order:: Changing the list of files. +* Find File At Point:: Make Ido guess the context. +* Ignoring:: Ignorance is bliss. +* Misc Customization:: Miscellaneous customization for Ido. +@end menu + +@node Changing List Order +@section Changing List Order +@cindex changing order of the list + +@noindent +By default, the list of current files is most recent first, +oldest last, with the exception that the files visible in the +current frame are put at the end of the list. A hook exists to +allow other functions to order the list. For example, if you add: + +@example +(add-hook 'ido-make-buffer-list-hook 'ido-summary-buffers-to-end) +@end example + +@noindent +then all files matching "Summary" are moved to the end of the list. +(I find this handy for keeping the INBOX Summary and so on out of the +way.) It also moves files matching @samp{output\*$} to the end of the +list (these are created by AUCTeX when compiling.) Other functions +could be made available which alter the list of matching files (either +deleting or rearranging elements.) + +@node Find File At Point +@section Find File At Point +@cindex find file at point +@cindex ffap + +@noindent +Find File At Point, also known generally as ``ffap'', is an +intelligent system for opening files, and URLs. + +The following expression will make Ido guess the context: + +@example +(setq ido-use-filename-at-point 'guess) +@end example + +@c @defvr {User Option} ido-use-filename-at-point +@c If the value of this user option is non-@code{nil}, ... +@c @end defvr + +You can disable URL ffap support by toggling +@code{ido-use-url-at-point}. + +@defvr {User Option} ido-use-url-at-point +If the value of this user option is non-@code{nil}, Ido will look for +a URL at point. If found, call @code{find-file-at-point} to visit it. +@end defvr + +@node Ignoring +@section Ignoring Buffers and Files +@cindex ignoring +@cindex regexp, ignore buffers and files + +@noindent +Ido is capable of ignoring buffers, directories, files and extensions +using regular expression. + +@defvr {User Option} ido-ignore-buffers +This variable takes a list of regular expressions for buffers to +ignore in @code{ido-switch-buffer}. +@end defvr + +@defvr {User Option} ido-ignore-directories +This variable takes a list of regular expressions for (sub)directories +names to ignore in @code{ido-dired} and @code{ido-find-file}. +@end defvr + +@defvr {User Option} ido-ignore-files +This variable takes a list of regular expressions for files to ignore +in @code{ido-find-file}. +@end defvr + +@defvr {User Option} ido-ignore-unc-host-regexps +This variable takes a list of regular expressions matching UNC hosts +to ignore. The letter case will be ignored if +@code{ido-downcase-unc-hosts} is non-@code{nil}. +@end defvr + +@c @defvr {User Option} ido-work-directory-list-ignore-regexps + +To make Ido use @code{completion-ignored-extensions} you need to +enable it: + +@example +(setq ido-ignore-extensions t) +@end example + +Now you can customize @code{completion-ignored-extensions} as well. +Go ahead and add all the useless object files, backup files, shared +library files and other computing flotsam you don’t want Ido to show. + +@strong{Please notice:} Ido will still complete the ignored elements +if it would otherwise not show any other matches. So if you type out +the name of an ignored file, Ido will still let you open it just fine. + +@node Misc Customization +@section Miscellaneous Customization +@cindex miscellaneous customization for Ido + +@defvr {User Option} ido-mode +This user option determines for which functional group (buffer and +files) Ido behavior should be enabled. +@end defvr + +@defvr {User Option} ido-case-fold +If the value of this user option is non-@code{nil}, searching of +buffer and file names should ignore case. +@end defvr + +@defvr {User Option} ido-show-dot-for-dired +If the value of this user option is non-@code{nil} , always put +@samp{.} as the first item in file name lists. This allows the +current directory to be opened immediately with Dired +@end defvr + +@defvr {User Option} ido-enable-dot-prefix +If the value of this user option is non-@code{nil}, Ido will match +leading dot as prefix. I.e., hidden files and buffers will match only +if you type a dot as first char (even if @code{ido-enable-prefix} is +@code{nil}). +@end defvr + +@c @defvr {User Option} ido-confirm-unique-completion +@c @defvr {User Option} ido-cannot-complete-command +@c @defvr {User Option} ido-record-commands +@c @defvr {User Option} ido-max-file-prompt-width +@c @defvr {User Option} ido-max-window-height +@c @defvr {User Option} ido-enable-last-directory-history +@c @defvr {User Option} ido-max-work-directory-list +@c @defvr {User Option} ido-enable-tramp-completion +@c @defvr {User Option} ido-unc-hosts +@c @defvr {User Option} ido-downcase-unc-hosts +@c @defvr {User Option} ido-cache-unc-host-shares-time +@c @defvr {User Option} ido-max-work-file-list +@c @defvr {User Option} ido-work-directory-match-only +@c @defvr {User Option} ido-auto-merge-work-directories-length +@c @defvr {User Option} ido-auto-merge-delay-time +@c @defvr {User Option} ido-auto-merge-inhibit-characters-regexp +@c @defvr {User Option} ido-merged-indicator +@c @defvr {User Option} ido-max-dir-file-cache +@c @defvr {User Option} ido-max-directory-size +@c @defvr {User Option} ido-rotate-file-list-default +@c @defvr {User Option} ido-enter-matching-directory +@c @defvr {User Option} ido-create-new-buffer +@c @defvr {User Option} ido-setup-hook +@c @defvr {User Option} ido-separator +@c @defvr {User Option} ido-decorations +@c @defvr {User Option} ido-use-virtual-buffers +@c @defvr {User Option} ido-use-faces +@c @defvr {User Option} ido-make-file-list-hook +@c @defvr {User Option} ido-make-dir-list-hook +@c @defvr {User Option} ido-make-buffer-list-hook +@c @defvr {User Option} ido-rewrite-file-prompt-functions +@c @defvr {User Option} ido-completion-buffer +@c @defvr {User Option} ido-completion-buffer-all-completions +@c @defvr {User Option} ido-all-frames +@c @defvr {User Option} ido-minibuffer-setup-hook +@c @defvr {User Option} ido-save-directory-list-file +@c @defvr {User Option} ido-read-file-name-as-directory-commands +@c @defvr {User Option} ido-read-file-name-non-ido +@c @defvr {User Option} ido-before-fallback-functions +@c @defvr {User Option} ido-buffer-disable-smart-matches + +@node Misc +@chapter Miscellaneous +@cindex miscellaneous + +@noindent +After @kbd{C-x b} (@code{ido-switch-buffer}), the buffer at the head +of the list can be killed by pressing @kbd{C-k}. If the buffer needs +saving, you will be queried before the buffer is killed. + +Likewise, after @kbd{C-x C-f}, you can delete (i.e., physically +remove) the file at the head of the list with @kbd{C-k}. You will +always be asked for confirmation before deleting the file. + +If you enter @kbd{C-x b} to switch to a buffer visiting a given file, +and you find that the file you are after is not in any buffer, you can +press @kbd{C-f} to immediately drop into @code{ido-find-file}. And +you can switch back to buffer selection with @kbd{C-b}. + +@c @defun ido-magic-forward-char +@c @defun ido-magic-backward-char + +You can also use Ido in your Emacs Lisp programs: + +@example +(setq my-pkgs (list "CEDET" "Gnus" "Rcirc" "Tramp" "Org" "all-of-them")) +(ido-completing-read "What's your favorite package? " my-pkgs) +@end example + +@menu +* All Matching:: Seeing all the matching buffers or files. +* Replacement:: Replacement for @code{read-buffer} and @code{read-file-name}. +* Other Packages:: Don't want to depend on @code{ido-everywhere}? +@end menu + +@node All Matching +@section All Matching +@cindex all matching +@cindex seeing all the matching buffers or files + +@noindent +If you have many matching files, they may not all fit onto one line of +the minibuffer. Normally, the minibuffer window will grow to show you +more of the matching files (depending on the value of the variables +@code{resize-mini-windows} and @code{max-mini-window-height}). If you +want Ido to behave differently from the default minibuffer resizing +behavior, set the variable @code{ido-max-window-height}. + +Also, to improve the responsiveness of Ido, the maximum number of +matching items is limited to 12, but you can increase or removed this +limit via the @code{ido-max-prospects} user option. + +@c @defvr {User Option} ido-max-prospects + +To see a full list of all matching buffers in a separate buffer, hit +@kbd{?} or press @key{TAB} when there are no further completions to +the substring. Repeated @key{TAB} presses will scroll you through +this separate buffer. + +@node Replacement +@section Replacement + +@noindent +@code{ido-read-buffer} and @code{ido-read-file-name} have been written +to be drop in replacements for the normal buffer and file name reading +functions @code{read-buffer} and @code{read-file-name}. + +To use ido for all buffer and file selections in Emacs, customize the +variable @code{ido-everywhere}. + +@c @defun ido-everywhere +@c @defvr {User Option} ido-everywhere + +@node Other Packages +@section Other Packages +@cindex other packages +@cindex used by other packages + +@noindent +If you don't want to rely on the @code{ido-everywhere} functionality, +@code{ido-read-buffer}, @code{ido-read-file-name}, and +@code{ido-read-directory-name} can be used by other packages to read a +buffer name, a file name, or a directory name in the @emph{Ido} way. + +@c @node Cheetsheet + +@c * History and Acknowledgments:: How Ido came into being +@c @node History and Acknowledgments +@c @appendix History and Acknowledgments + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include doclicense.texi + +@c @node Function Index +@c @unnumbered Function Index + +@c @printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + +@bye |