@copying
This file documents the Ido package for GNU Emacs.
-Copyright @copyright{} 2013 Free Software Foundation, Inc.
+Copyright @copyright{} 2013-2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
-@dircategory Emacs lisp libraries
+@dircategory Emacs misc features
@direntry
-* Ido: (ido). Interactively do things with buffers and files.
+* Ido: (ido). Interactively do things with buffers and files.
@end direntry
@finalout
@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.
+* 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.
+* GNU Free Documentation License:: The license for this documentation.
Indexes
-* Variable Index:: An entry for each documented variable.
+* Variable Index:: An entry for each documented variable.
@detailmenu
--- The Detailed Node Listing ---
Overview
-* Activation:: How to use this package.
+* Activation:: How to use this package.
+* Working Directories:: Where files have most recently been opened.
Matching
-* Interactive Substring Matching:: Interactivity, matching, scrolling.
-* Prefix Matching:: Standard completion.
-* Flexible Matching:: More flexible matching.
-* Regexp Matching:: Matching using regular expression.
+* 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.
+* 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}?
+* 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
@file{iswitchb.el} package by Stephen Eglen.
@menu
-* Activation:: How to use this package.
+* Activation:: How to use this package.
+* Working Directories:: Where files have most recently been opened.
@end menu
@node Activation
(ido-mode t)
@end example
-@c @node Working Directories
-@c @section Working Directories
-@c @cindex working directories
+@node Working Directories
+@section Working Directories
+@cindex working directories
+
+@vindex ido-work-directory-list
+@noindent
+@dfn{Working directories} are directories where files have most
+recently been opened. The current directory is inserted at the front
+of this @code{ido-work-directory-list} whenever a file is opened with
+@code{ido-find-file} and other file-related functions.
+
+@c @cindex merge
+@c or maybe a new node for ``merge''
+
+@c @deffn Command ido-merge-work-directories
+
+@c @deffn Command ido-prev-work-directory
+
+@c @deffn Command ido-next-work-directory
+
+@c @deffn Command ido-forget-work-directory
+
+@c @defvar ido-use-merged-list
+@c @defvar ido-try-merged-list
+@c @defvar ido-pre-merge-state
+
+@defopt ido-max-work-directory-list
+This user option specifies maximum number of working directories to
+record.
+@end defopt
+
+@c see (info "(elisp) File Name Completion")
+@defopt ido-max-dir-file-cache
+This user option specifies maximum number of working directories to be
+cached. This is the size of the cache of
+@code{file-name-all-completions} results. Each cache entry is time
+stamped with the modification time of the directory. Some systems,
+like MS-Windows, have unreliable directory modification times, so you
+may choose to disable caching on such systems, or explicitly refresh
+the cache contents using the command @code{ido-reread-directory}
+(usually @kbd{C-l}) in the minibuffer.
+@end defopt
@node Matching
@chapter Matching
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.
+* 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
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.
+of the list and then press @key{RET} to select it.
However, if you type @kbd{4}, you'll only have one match left:
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
+@c @deffn Command ido-delete-backward-updir
@cindex root directory
@cindex home directory
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}.
+@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
+@c @defopt ido-record-ftp-work-directories
+@c @defopt ido-merge-ftp-work-directories
+@c @defopt ido-cache-ftp-work-directory-time
+@c @defopt ido-slow-ftp-hosts
+@c @defopt 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
@code{ido-switch-buffer}.
@c @kindex C-x b
-@c @findex ido-switch-buffer
-@c @defun ido-switch-buffer
+@c @deffn Command ido-switch-buffer
@c This command switch to another buffer interactively.
-@c @end defun
+@c @end deffn
@c @kindex C-x C-f
-@c @findex ido-find-file
-@c @defun ido-find-file
+@c @deffn Command ido-find-file
@c Edit file with name obtained via minibuffer.
-@c @end defun
+@c @end deffn
@c @kindex C-x d
@c @findex ido-dired
-@c @defun ido-dired
+@c @deffn Command ido-dired
@c Call Dired the Ido way.
-@c @end defun
+@c @end deffn
@node Prefix Matching
@section Prefix Matching
the only difference to the description of the substring matching
above.
+@cindex toggle prefix matching
You can toggle prefix matching with @kbd{C-p}
(@code{ido-toggle-prefix}).
@section Flexible Matching
@cindex flexible matching
-@defvr {User Option} ido-enable-flex-matching
+@defopt 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
+@end defopt
@noindent
If @code{ido-enable-flex-matching} is non-@code{nil}, Ido will do a
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
+@defopt 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
+@end defopt
@strong{Please notice:} Ido-style completion is inhibited when you
enable regexp matching.
You can toggle display of the hidden buffers and files with @kbd{C-a}
(@code{ido-toggle-ignore}).
-@c @defun ido-toggle-ignore
+@c @deffn Command ido-toggle-ignore
@node Customization
@chapter Customization
(define-key ido-completion-map " " 'ido-next-match))
@end example
+@c @defopt ido-setup-hook
+@c a new node for Ido hooks?
+
@menu
* Changing List Order:: Changing the list of files.
* Find File At Point:: Make Ido guess the context.
(setq ido-use-filename-at-point 'guess)
@end example
-@c @defvr {User Option} ido-use-filename-at-point
+@c @defopt ido-use-filename-at-point
@c If the value of this user option is non-@code{nil}, ...
-@c @end defvr
+@c @end defopt
You can disable URL ffap support by toggling
@code{ido-use-url-at-point}.
-@defvr {User Option} ido-use-url-at-point
+@defopt 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
+@end defopt
@node Ignoring
@section Ignoring Buffers and Files
Ido is capable of ignoring buffers, directories, files and extensions
using regular expression.
-@defvr {User Option} ido-ignore-buffers
+@defopt ido-ignore-buffers
This variable takes a list of regular expressions for buffers to
ignore in @code{ido-switch-buffer}.
-@end defvr
+@end defopt
-@defvr {User Option} ido-ignore-directories
+@defopt 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
+@end defopt
-@defvr {User Option} ido-ignore-files
+@defopt ido-ignore-files
This variable takes a list of regular expressions for files to ignore
in @code{ido-find-file}.
-@end defvr
+@end defopt
-@defvr {User Option} ido-ignore-unc-host-regexps
+@defopt 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
+@end defopt
-@c @defvr {User Option} ido-work-directory-list-ignore-regexps
+@c FIXME: Where to add this variable? This node or ``working directory''?
+@c @defopt ido-work-directory-list-ignore-regexps
To make Ido use @code{completion-ignored-extensions} you need to
enable it:
@section Miscellaneous Customization
@cindex miscellaneous customization for Ido
-@defvr {User Option} ido-mode
+@c Variables described in this sections may be moved to new nodes in
+@c the future.
+
+@defopt ido-mode
This user option determines for which functional group (buffer and
files) Ido behavior should be enabled.
-@end defvr
+@end defopt
-@defvr {User Option} ido-case-fold
+@defopt 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
+@end defopt
-@defvr {User Option} ido-show-dot-for-dired
-If the value of this user option is non-@code{nil} , always put
+@defopt 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
+@end defopt
-@defvr {User Option} ido-enable-dot-prefix
+@defopt 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
+@end defopt
+
+@defopt ido-confirm-unique-completion
+If the value of this user option is non-@code{nil}, even a unique
+completion must be confirmed. This means that @code{ido-complete}
+(@key{TAB}) must always be followed by @code{ido-exit-minibuffer}
+(@key{RET}) even when there is only one unique completion.
+@end defopt
+
+@defopt ido-cannot-complete-command
+When @code{ido-complete} can't complete any more, it will run the
+command specified by this user option. The most useful values are
+@code{ido-completion-help}, which pops up a window with completion
+alternatives, or @code{ido-next-match} or @code{ido-prev-match}, which
+cycle the buffer list.
+@end defopt
+
+@defopt ido-max-file-prompt-width
+This user option specifies the upper limit of the prompt string. If
+its value is an integer, it specifies the number of characters of the
+string. If its value is a floating point number, it specifies a
+fraction of the frame width.
+@end defopt
+
+@defopt ido-max-window-height
+If the value of this user option is non-@code{nil}, its value will
+override the variable @code{max-mini-window-height}, which is the
+maximum height for resizing mini-windows (the minibuffer and the echo
+area). If it's a floating point number, it specifies a fraction of
+the mini-window frame's height. If it's an integer, it specifies the
+number of lines.
+@end defopt
+
+@defopt ido-record-commands
+If the value of this user option is non-@code{nil}, Ido will record
+commands in the variable @code{command-history}. Note that non-Ido
+equivalent is recorded.
+@end defopt
+
+@defopt ido-all-frames
+This user option will be passed to @code{walk-windows} as its
+@var{all-frames} argument when Ido is finding buffers. @xref{Cyclic
+Window Ordering, , Cyclic Ordering of Windows, elisp, GNU Emacs Lisp
+Reference Manual}.
+@end defopt
+
+@defopt ido-minibuffer-setup-hook
+This hook variable contains Ido-specific customization of minibuffer
+setup. It is run during minibuffer setup if Ido is active, and is
+intended for use in customizing ido for interoperation with other
+packages.
+@end defopt
+
+@c @defopt ido-enable-tramp-completion
+@c cross-reference to tramp.texi
+
+@c @cindex UNC host names, completion
+@c @defopt ido-unc-hosts
+@c @defopt ido-downcase-unc-hosts
+@c @defopt ido-cache-unc-host-shares-time
+
+@c @defopt ido-enable-last-directory-history
+@c @defopt ido-max-work-file-list
+@c @defopt ido-work-directory-match-only
+@c @defopt ido-auto-merge-work-directories-length
+@c @defopt ido-auto-merge-delay-time
+@c @defopt ido-auto-merge-inhibit-characters-regexp
+@c @defopt ido-merged-indicator
+@c @defopt ido-max-directory-size
+@c @defopt ido-rotate-file-list-default
+@c @defopt ido-enter-matching-directory
+@c @defopt ido-create-new-buffer
+@c @defopt ido-separator
+@c @defopt ido-decorations
+@c @defopt ido-use-virtual-buffers
+@c @defopt ido-use-faces
+@c @defopt ido-make-file-list-hook
+@c @defopt ido-make-dir-list-hook
+@c @defopt ido-make-buffer-list-hook
+@c @defopt ido-rewrite-file-prompt-functions
+@c @defopt ido-completion-buffer
+@c @defopt ido-completion-buffer-all-completions
+@c @defopt ido-save-directory-list-file
+@c @defopt ido-read-file-name-as-directory-commands
+@c @defopt ido-read-file-name-non-ido
+@c @defopt ido-before-fallback-functions
+@c @defopt ido-buffer-disable-smart-matches
@node Misc
@chapter Miscellaneous
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
+@c @deffn Command ido-magic-forward-char
+@c @deffn Command ido-magic-backward-char
You can also use Ido in your Emacs Lisp programs:
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
+@c @defopt 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
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
+@c @deffn Command ido-everywhere
+@c @defopt ido-everywhere
@node Other Packages
@section Other Packages
@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 @node Cheatsheet
@c * History and Acknowledgments:: How Ido came into being
@c @node History and Acknowledgments