--- /dev/null
+\input texinfo @c -*- texinfo -*-
+@c %**start of header
+@setfilename ./ivy.info
+@settitle Ivy User Manual
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@copying
+@ifnottex
+Ivy manual, version 0.7.0
+
+Ivy is an interactive interface for completion in Emacs. Emacs uses
+completion mechanism in a variety of contexts: code, menus, commands,
+variables, functions, etc. Completion entails listing, sorting,
+filtering, previewing, and applying actions on selected items. When
+active, @code{ivy-mode} completes the selection process by narrowing
+available choices while previewing in the minibuffer. Selecting the
+final candidate is either through simple keyboard character inputs or
+through powerful regular expressions. @end ifnottex
+
+Copyright @copyright{} 2015 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
+@direntry
+* Ivy: (ivy). Using Ivy for completion.
+@end direntry
+
+@finalout
+@titlepage
+@title Ivy User Manual
+@author Oleh Krehel
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Ivy User Manual
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction::
+* Installation::
+* Getting started::
+* Key bindings::
+* Completion styles::
+* Variable Index::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Installation
+
+* Installing from Emacs Package Manager::
+* Installing from the Git repository::
+
+Getting started
+
+* Basic customization::
+
+Key bindings
+
+* Global key bindings::
+* Minibuffer key bindings::
+
+Minibuffer key bindings
+
+* Key bindings for navigation::
+* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
+* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
+* Key bindings that alter minibuffer input::
+* Other key bindings::
+* Hydra in the minibuffer::
+* Saving the current completion session to a buffer::
+Completion styles
+
+* ivy--regex-plus::
+* ivy--regex-ignore-order::
+* ivy--regex-fuzzy::
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+Ivy is for quick and easy selection from a list. When Emacs prompts
+for a string from a list of several possible choices, Ivy springs into
+action to assist in narrowing and picking the right string from a vast
+number of choices.
+
+Ivy strives for minimalism, simplicity, customizability and
+discoverability.
+
+@subsubheading Minimalism
+Uncluttered minibuffer is minimalism. Ivy shows the completion
+defaults, the number of matches, and 10 candidate matches below the
+input line. Customize @code{ivy-length} to adjust the number of candidate
+matches displayed in the minibuffer.
+
+@subsubheading Simplicity
+Simplicity is about Ivy's behavior in the minibuffer. It is also about
+the code interface to extend Ivy's functionality. The minibuffer area
+behaves as close to @code{fundamental-mode} as possible. @kbd{SPC} inserts a
+space, for example, instead of being bound to the more complex
+@code{minibuffer-complete-word}. Ivy's code uses easy-to-examine global
+variables; avoids needless complications with branch-introducing
+custom macros.
+
+@subsubheading Customizability
+Customizability is about being able to use different methods and
+interfaces of completion to tailor the selection process. For example,
+adding a custom display function that points to a selected candidate
+with @code{->}, instead of highlighting the selected candidate with the
+@code{ivy-current-match} face. Or take the customization of actions, say
+after the candidate function is selected. @kbd{RET} uses
+@code{counsel-describe-function} to describe the function, whereas @kbd{M-o d}
+jumps to that function's definition in the code. The @kbd{M-o} prefix can
+be uniformly used with characters like @kbd{d} to group similar actions.
+
+@subsubheading Discoverability
+Ivy displays easily discoverable commands through the hydra facility.
+@kbd{C-o} in the minibuffer displays a hydra menu. It opens up within an
+expanded minibuffer area. Each menu item comes with short
+documentation strings and highlighted one-key completions. So
+discovering even seldom used keys is simply a matter of @kbd{C-o} in the
+minibuffer while in the midst of the Ivy interaction. This
+discoverability minimizes exiting Ivy interface for documentation
+look-ups.
+
+@node Installation
+@chapter Installation
+
+Install Ivy automatically through Emacs's package manager, or manually
+from Ivy's development repository.
+@menu
+* Installing from Emacs Package Manager::
+* Installing from the Git repository::
+@end menu
+
+@node Installing from Emacs Package Manager
+@section Installing from Emacs Package Manager
+
+@kbd{M-x} @code{package-install} @kbd{RET} @code{swiper} @kbd{RET}
+
+Ivy is installed as part of @code{swiper} package. @code{swiper} is available
+from two different package archives, GNU ELPA and MELPA. For the
+latest stable version, use the GNU ELPA archives using the above M-x
+command.
+
+For current hourly builds, use the MELPA archives. See the code below
+for adding MELPA to the list of package archives:
+
+
+@lisp
+(require 'package)
+(add-to-list 'package-archives
+ '("melpa" . "http://melpa.org/packages/"))
+@end lisp
+
+After this do @kbd{M-x} @code{package-refresh-contents} @kbd{RET}, followed by
+@kbd{M-x} @code{package-install} @kbd{RET} @code{swiper} @kbd{RET}.
+
+For package manager details, see @ref{Packages,,,emacs,}.
+
+@node Installing from the Git repository
+@section Installing from the Git repository
+
+Why install from Git?
+
+@itemize
+@item
+No need to wait for MELPA's hourly builds
+@item
+Easy to revert to previous versions
+@item
+Contribute to Ivy's development; send patches; pull requests
+@end itemize
+
+@strong{Configuration steps}
+
+First clone the Swiper repository:
+
+@example
+cd ~/git && git clone https://github.com/abo-abo/swiper
+cd swiper && make compile
+@end example
+
+Then add this to Emacs init:
+
+@lisp
+(add-to-list 'load-path "~/git/swiper/")
+(require 'ivy)
+@end lisp
+
+To update the code:
+
+@example
+git pull
+make
+@end example
+
+@node Getting started
+@chapter Getting started
+
+First enable Ivy completion everywhere:
+
+
+@lisp
+(ivy-mode 1)
+@end lisp
+
+Note: @code{ivy-mode} can be toggled on and off with @kbd{M-x} @code{ivy-mode}.
+@menu
+* Basic customization::
+@end menu
+
+@node Basic customization
+@section Basic customization
+
+Here are some basic settings particularly useful for new Ivy
+users:
+
+@lisp
+(setq ivy-use-virtual-buffers t)
+(setq ivy-height 10)
+(setq ivy-display-style 'fancy)
+(setq ivy-count-format "(%d/%d) ")
+@end lisp
+
+For additional customizations, refer to @code{M-x describe-variable}
+documentation.
+
+@node Key bindings
+@chapter Key bindings
+
+@menu
+* Global key bindings::
+* Minibuffer key bindings::
+@end menu
+
+@node Global key bindings
+@section Global key bindings
+
+Recommended key bindings are:
+@subsubheading Ivy-based interface to standard commands
+
+@lisp
+(global-set-key (kbd "C-s") 'swiper)
+(global-set-key (kbd "M-x") 'counsel-M-x)
+(global-set-key (kbd "C-x C-f") 'counsel-find-file)
+(global-set-key (kbd "<f1> f") 'counsel-describe-function)
+(global-set-key (kbd "<f1> v") 'counsel-describe-variable)
+(global-set-key (kbd "<f1> l") 'counsel-load-library)
+(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
+(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
+@end lisp
+@subsubheading Ivy-based interface to shell and system tools
+
+@lisp
+(global-set-key (kbd "C-c g") 'counsel-git)
+(global-set-key (kbd "C-c j") 'counsel-git-grep)
+(global-set-key (kbd "C-c k") 'counsel-ag)
+(global-set-key (kbd "C-x l") 'counsel-locate)
+(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
+@end lisp
+@subsubheading Ivy-resume and other commands
+@code{ivy-resume} resumes the last Ivy-based completion.
+
+@lisp
+(global-set-key (kbd "C-c C-r") 'ivy-resume)
+@end lisp
+
+@node Minibuffer key bindings
+@section Minibuffer key bindings
+
+Ivy includes several minibuffer bindings, which are defined in the
+@code{ivy-minibuffer-map} keymap variable. The most frequently used ones
+are described here.
+
+@code{swiper} or @code{counsel-M-x} add more through the @code{keymap} argument to
+@code{ivy-read}. These keys, also active in the minibuffer, are described
+under their respective commands.
+@menu
+* Key bindings for navigation::
+* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
+* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
+* Key bindings that alter minibuffer input::
+* Other key bindings::
+* Hydra in the minibuffer::
+* Saving the current completion session to a buffer::
+@end menu
+
+@node Key bindings for navigation
+@subsection Key bindings for navigation
+
+@itemize
+@item
+@kbd{C-n} (@code{ivy-next-line}) selects the next candidate
+@item
+@kbd{C-p} (@code{ivy-previous-line}) selects the previous candidate
+@item
+@kbd{M-<} (@code{ivy-beginning-of-buffer}) selects the first candidate
+@item
+@kbd{M->} (@code{ivy-end-of-buffer}) selects the last candidate
+@item
+@kbd{C-v} (@code{ivy-scroll-up-command}) scrolls up by @code{ivy-height} lines
+@item
+@kbd{M-v} (@code{ivy-scroll-down-command}) scrolls down by @code{ivy-height} lines
+@end itemize
+
+@defopt ivy-wrap
+This user option allows to get the wrap-around behavior for @kbd{C-n} and
+@kbd{C-p}. When set to @code{t}, @code{ivy-next-line} and @code{ivy-previous-line} will
+cycle past the last and the first candidates respectively.
+
+This behavior is off by default.
+@end defopt
+
+@defopt ivy-height
+Use this variable to adjust the minibuffer height, and therefore the
+scroll size for @kbd{C-v} and @kbd{M-v}.
+@end defopt
+
+@node Key bindings for single selection action then exit minibuffer
+@subsection Key bindings for single selection, action, then exit minibuffer
+
+Ivy can offer several actions from which to choose which action to
+run. This "calling an action" operates on the selected candidate. For
+example, when viewing a list of files, one action could open it for
+editing, one to view it, another to invoke a special function, and so
+on. Custom actions can be added to this interface. The precise action
+to call on the selected candidate can be delayed until after the
+narrowing is completed. No need to exit the interface if unsure which
+action to run. This delayed flexibility and customization of actions
+extends usability of lists in Emacs.
+
+@kbd{C-m} or @kbd{RET} (@code{ivy-done}) calls the default action and exits the
+minibuffer.
+
+@kbd{M-o} (@code{ivy-dispatching-done}) presents all available valid actions
+from which to choose. When there is only one action available, there
+is no difference between @kbd{M-o} and @kbd{C-m}.
+
+@kbd{C-j} (@code{ivy-alt-done}) calls the alternate action, such as completing
+a directory name in a file list whereas @kbd{C-m} will select that directory
+and exit the minibuffer.
+
+Exiting the minibuffer also closes the Ivy window (as specified by
+@code{ivy-height}). This closing and exiting sequence is conveniently off
+when applying multiple actions. Multiple actions and multiple
+selections as covered in the next section of this manual.
+
+@kbd{TAB} (@code{ivy-partial-or-done}) attempts partial completion, extending
+current input as much as possible.
+
+@kbd{TAB TAB} is the same as @kbd{C-j}.
+
+@kbd{C-M-j} (@code{ivy-immediate-done}) is useful when there is no match for
+the given input. Or there is an incorrect partial match. @kbd{C-M-j} with
+@code{find-file} lists ignores the partial match and instead takes the
+current input to create a new directory with @code{dired-create-directory}.
+
+@code{ivy-immediate-done} illustrates how Ivy distinguishes between calling
+an action on the @emph{currently selected} candidate and calling an action
+on the @emph{current input}.
+
+Invoking avy completion with @kbd{C-'} (@code{ivy-avy}).
+@kbd{C-`} uses avy's visible jump mechanism, which can further reduce
+Ivy's line-by-line scrolling that requires multiple @kbd{C-n} or @kbd{C-p}
+keystrokes.
+
+@node Key bindings for multiple selections and actions keep minibuffer open
+@subsection Key bindings for multiple selections and actions, keep minibuffer open
+
+For repeatedly applying multiple actions or acting on multiple
+candidates, Ivy does not close the minibuffer between commands. It
+keeps the minibuffer open for applying subsequent actions.
+
+Adding an extra meta key to the normal key chord invokes the special
+version of the regular commands that enables applying multiple
+actions.
+
+@kbd{C-M-m} (@code{ivy-call}) is the non-exiting version of the default action,
+@kbd{C-m} (@code{ivy-done}). Instead of closing the minibuffer, @kbd{C-M-m} allows
+selecting another candidate or another action. For example, @kbd{C-M-m} on
+functions list invokes @code{describe-function}. When combined with @kbd{C-n},
+function descriptions can be invoked quickly in succession.
+
+@kbd{RET} exits the minibuffer.
+
+@code{ivy-resume} recalls the state of the completion session just before
+its last exit. Useful after an accidental @kbd{C-m} (@code{ivy-done}).
+
+@kbd{C-M-o} (@code{ivy-dispatching-call}) is a non-exiting version of @kbd{M-o}
+(@code{ivy-dispatching-done}) that can accumulate candidates into a queue.
+For example, for playback in @code{counsel-rhythmbox}, @kbd{C-M-o e} en-queues
+the selected candidate, and @kbd{C-n C-m} plays the next one in the queue.
+
+@kbd{C-M-n} (@code{ivy-next-line-and-call}) combines @kbd{C-n} and @kbd{C-M-m}. Applies
+an action and moves to next line. Comes in handy when opening multiple
+files from @code{counsel-find-file}, @code{counsel-git-grep}, @code{counsel-ag}, or
+@code{counsel-locate} lists. Just hold @kbd{C-M-n} for rapid-fire default
+action on each successive element of the list.
+
+@kbd{C-M-p} (@code{ivy-previous-line-and-call}) combines @kbd{C-p} and @kbd{C-M-m}. Is
+the same as above except that it moves through the list in the other
+direction.
+
+@node Key bindings that alter minibuffer input
+@subsection Key bindings that alter minibuffer input
+
+@kbd{M-n} (@code{ivy-next-history-element}) and @kbd{M-p}
+(@code{ivy-previous-history-element}) cycle through the Ivy command
+history. Ivy updates an internal history list after each action. When
+this history list is empty, @kbd{M-n} inserts symbol (or URL) at point
+into the minibuffer.
+
+@kbd{M-i} (@code{ivy-insert-current}) inserts the current candidate into the
+minibuffer. Useful for copying and renaming files, for example: @kbd{M-i}
+to insert the original file name string, edit it, and then @kbd{C-m} to
+complete the renaming.
+
+@kbd{M-j} (@code{ivy-yank-word}) inserts sub-word at point into minibuffer. This
+is similar to @kbd{C-s C-w} with @code{isearch}. Ivy reserves @kbd{C-w} for
+@code{kill-region}.
+
+@kbd{S-SPC} (@code{ivy-restrict-to-matches}) deletes the current input, and
+resets the candidates list to the currently restricted matches. This
+is how Ivy provides narrowing in successive tiers.
+
+@kbd{C-r} (@code{ivy-reverse-i-search}) works just like @kbd{C-r} at bash command
+prompt, where the completion candidates are the history items. Upon
+completion, the selected candidate string is inserted into the
+minibuffer.
+
+@node Other key bindings
+@subsection Other key bindings
+
+@kbd{M-w} (@code{ivy-kill-ring-save}) copies selected candidates to the kill
+ring; when the region is active, copies active region.
+
+@node Hydra in the minibuffer
+@subsection Hydra in the minibuffer
+
+@kbd{C-o} (@code{hydra-ivy/body}) invokes Hydra menus with key shortcuts.
+
+@kbd{C-o} or @kbd{i} resumes editing.
+
+Hydra reduces key strokes, for example: @kbd{C-n C-n C-n C-n} is @kbd{C-o
+jjjj} in Hydra. Hydra has other benefits besides certain shorter key
+bindings:
+@itemize
+@item
+@kbd{<} and @kbd{>} to adjust height of minibuffer,
+@item
+describes the current completion state, such as case folding and the
+current action.
+@end itemize
+
+Minibuffer editing is disabled when Hydra is active.
+
+@node Saving the current completion session to a buffer
+@subsection Saving the current completion session to a buffer
+
+@kbd{C-c C-o} (@code{ivy-occur}) saves the current candidates to a new buffer;
+the list is active in the new buffer.
+
+@kbd{RET} or @kbd{mouse-1} in the new buffer calls the appropriate action on
+the selected candidate.
+
+Ivy has no limit on the number of active buffers like these.
+
+Ivy takes care of making these buffer names unique. It applies
+descriptive names, for example: @code{*ivy-occur counsel-describe-variable
+"function$*}.
+
+@node Completion styles
+@chapter Completion styles
+
+Ivy's completion functions rely on the highly configurable regex
+builder.
+
+The default is:
+
+@lisp
+(setq ivy-re-builders-alist
+ '((t . ivy--regex-plus)))
+@end lisp
+
+The default @code{ivy--regex-plus} narrowing is always invoked unless
+specified otherwise. For example, file name completion may have a
+custom completion function:
+
+@lisp
+(setq ivy-re-builders-alist
+ '((read-file-name-internal . ivy--regex-fuzzy)
+ (t . ivy--regex-plus)))
+@end lisp
+
+Ivy's flexibility extends to using different styles of completion
+mechanics (regex-builders) for different types of lists. Despite this
+flexibility, Ivy operates within a consistent and uniform interface.
+The main regex-builders currently in Ivy are:
+@menu
+* ivy--regex-plus::
+* ivy--regex-ignore-order::
+* ivy--regex-fuzzy::
+@end menu
+
+@node ivy--regex-plus
+@section ivy--regex-plus
+
+@code{ivy--regex-plus} is Ivy's default completion method.
+
+@code{ivy--regex-plus} matches by splitting the input by spaces and
+rebuilding it into a regex.
+
+As the search string is typed in Ivy's minibuffer, it is transformed
+into proper regex syntax. If the string is "for example", it is
+transformed into
+
+@verbatim
+"\\(for\\).*\\(example\\)"
+@end verbatim
+
+which in regex terminology matches "for" followed by a wild card and
+then "example". Note how Ivy uses the space character to build
+wild cards. For literal white space matching in Ivy, use an extra space:
+to match one space type two spaces, to match two spaces type three
+spaces, and so on.
+
+As Ivy transforms typed characters into regex strings, it provides an
+intuitive feedback through font highlights.
+
+Ivy supports regexp negation with "!". For example, "define key ! ivy
+quit" first selects everything matching "define.*key", then removes
+everything matching "ivy", and finally removes everything matching
+"quit". What remains is the final result set of the negation regexp.
+
+@verbatim
+Standard regexp identifiers work:
+
+"^", "$", "\b" or "[a-z]"
+@end verbatim
+
+Since Ivy treats minibuffer input as a regexp, standard regexp
+identifiers work as usual. The exceptions are spaces, which
+translate to ".*", and "!" that signal the beginning of a negation
+group.
+
+@node ivy--regex-ignore-order
+@section ivy--regex-ignore-order
+
+@code{ivy--regex-ignore-order} ignores the order of regexp tokens when
+searching for matching candidates. For instance, the input "for
+example" will match "example test for". Otherwise @code{ivy--regex-plus}
+normal behavior is to honor the order of regexp tokens.
+
+@node ivy--regex-fuzzy
+@section ivy--regex-fuzzy
+
+@code{ivy--regex-fuzzy} splits each character with a wild card. Searching
+for "for" returns all "f.*o.*r" matches, resulting in a large number
+of hits. Yet some searches need these extra hits. Ivy sorts such
+large lists using @code{flx} package's scoring mechanism, if it's
+installed.
+
+@node Variable Index
+@chapter Variable Index
+
+@printindex vr
+
+@bye