* doc/misc/ido.texi: New file.

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