branch: master
commit 84533bb7bfe482eadf24ede674df02e86a1b8d25
Author: Oleh Krehel <ohwoeo...@gmail.com>
Commit: Oleh Krehel <ohwoeo...@gmail.com>
Minor fixes to ivy.org and export to ivy.texi
Fixes #304
---
doc/ivy.org | 66 +++---
doc/ivy.texi | 649 +++++++++++++++++++++++++++++++---------------------------
2 files changed, 382 insertions(+), 333 deletions(-)
diff --git a/doc/ivy.org b/doc/ivy.org
index 28dc6e3..1ddea11 100644
--- a/doc/ivy.org
+++ b/doc/ivy.org
@@ -26,7 +26,7 @@ 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 mini buffer. Selecting the
+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
@@ -57,10 +57,10 @@ discoverability.
#+BEGIN_TEXINFO
@subsubheading Minimalism
#+END_TEXINFO
-Uncluttered minibuffer is minimalism. Ivy shows completion
-defaults, number of matches, and 10 candidate matches below the input
-line. Customize =ivy-length= to adjust the number of candidate matches
-displayed in the minibuffer.
+Uncluttered minibuffer is minimalism. Ivy shows the completion
+defaults, the number of matches, and 10 candidate matches below the
+input line. Customize =ivy-length= to adjust the number of candidate
+matches displayed in the minibuffer.
#+BEGIN_TEXINFO
@subsubheading Simplicity
@@ -117,7 +117,7 @@ for adding MELPA to the list of package archives:
#+begin_src elisp
(require 'package)
-(add-to-list 'package-archives
+(add-to-list 'package-archives
'("melpa" . "http://melpa.org/packages/";))
#+end_src
@@ -128,7 +128,7 @@ For package manager details, see [[info:emacs#Packages]].
** Installing from the Git repository
-Why install from Git?
+Why install from Git?
- No need to wait for MELPA's hourly builds
- Easy to revert to previous versions
@@ -162,7 +162,7 @@ First enable Ivy completion everywhere:
(ivy-mode 1)
#+end_src
-Note: =ivy-mode= can be toggled on and off with ~M-x~ =ivy-mode=.
+Note: =ivy-mode= can be toggled on and off with ~M-x~ =ivy-mode=.
** Basic customization
Here are some basic settings particularly useful for new Ivy
users:
@@ -261,7 +261,7 @@ a directory name in a file list whereas ~C-m~ will select
that directory
and exit the minibuffer.
Exiting the minibuffer also closes the Ivy window (as specified by
-=Ivy-height=). This closing and exiting sequence is conveniently off
+=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.
@@ -290,19 +290,19 @@ keystrokes.
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.
+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.
+actions.
~C-M-m~ (=ivy-call=) is the non-exiting version of the default action,
~C-m~ (=ivy-done=). Instead of closing the minibuffer, ~C-M-m~ allows
selecting another candidate or another action. For example, ~C-M-m~ on
functions list invokes =describe-function=. When combined with ~C-n~,
-function descriptions can be invoked quickly in succession.
+function descriptions can be invoked quickly in succession.
-~RET~ exists the minibuffer.
+~RET~ exits the minibuffer.
=ivy-resume= recalls the state of the completion session just before
its last exit. Useful after an accidental ~C-m~ (=ivy-done=).
@@ -328,9 +328,9 @@ direction.
(=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, ~M-n~ inserts symbol (or URL) at point
-into minibuffer.
+into the minibuffer.
-~M-i~ (=ivy-insert-current=) inserts current candidate into
+~M-i~ (=ivy-insert-current=) inserts the current candidate into the
minibuffer. Useful for copying and renaming files, for example: ~M-i~
to insert the original file name string, edit it, and then ~C-m~ to
complete the renaming.
@@ -339,9 +339,9 @@ complete the renaming.
is similar to ~C-s C-w~ with =isearch=. Ivy reserves ~C-w~ for
=kill-region=.
-~S-SPC~ (=ivy-restrict-to-matches=) deletes current input, and resets
-candidates list to previous state. This is how Ivy provides narrowing
-in successive tiers.
+~S-SPC~ (=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.
~C-r~ (=ivy-reverse-i-search=) works just like ~C-r~ at bash command
prompt, where the completion candidates are the history items. Upon
@@ -351,7 +351,7 @@ minibuffer.
*** Other key bindings
~M-w~ (=ivy-kill-ring-save=) copies selected candidates to the kill
-ring; when no candidates, copies active region.
+ring; when the region is active, copies active region.
*** Hydra in the minibuffer
@@ -362,19 +362,19 @@ ring; when no candidates, copies active region.
Hydra reduces key strokes, for example: ~C-n C-n C-n C-n~ is ~C-o
jjjj~ in Hydra. Hydra has other benefits besides certain shorter key
bindings:
-- ~<~ and ~>~ to adjust height of minibuffer
+- ~<~ and ~>~ to adjust height of minibuffer,
- describes the current completion state, such as case folding and the
- current action
+ current action.
-minibuffer editing is disabled when Hydra is active.
+Minibuffer editing is disabled when Hydra is active.
-*** Saving to buffer
+*** Saving the current completion session to a buffer
-~C-c C-o~ (=ivy-occur=) saves current candidates to a new buffer; the
-list is active in the new buffer
+~C-c C-o~ (=ivy-occur=) saves the current candidates to a new buffer;
+the list is active in the new buffer.
~RET~ or ~mouse-1~ in the new buffer calls the appropriate action on
-the selected candidate.
+the selected candidate.
Ivy has no limit on the number of active buffers like these.
@@ -387,7 +387,7 @@ descriptive names, for example: =*ivy-occur
counsel-describe-variable
Ivy's completion functions rely on the highly configurable regex
builder.
-The default is:
+The default is:
#+begin_src elisp
(setq ivy-re-builders-alist
'((t . ivy--regex-plus)))
@@ -409,14 +409,14 @@ The main regex-builders currently in Ivy are:
** ivy--regex-plus
-=ivy--regex-plus= is Ivy's default completion method.
+=ivy--regex-plus= is Ivy's default completion method.
=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
+transformed into
#+BEGIN_EXAMPLE
"\\(for\\).*\\(example\\)"
@@ -457,7 +457,7 @@ normal behavior is to honor the order of regexp tokens.
** ivy--regex-fuzzy
=ivy--regex-fuzzy= splits each character with a wild card. Searching
-for "for" returns all "f.*o.*r" matches, resulting in too many hits.
-Yet some searches need these extra hits. Ivy sorts such large lists
-using =flx= package's scoring mechanism.
-
+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 =flx= package's scoring mechanism, if it's
+installed.
diff --git a/doc/ivy.texi b/doc/ivy.texi
index a1fe0f5..811b59e 100644
--- a/doc/ivy.texi
+++ b/doc/ivy.texi
@@ -8,13 +8,16 @@
@copying
@ifnottex
-This manual is for Ivy version 0.7.0.
+Ivy manual, version 0.7.0
-Ivy is a completion interface for Emacs. When @code{ivy-mode} is active,
-any time another Elisp code requires completion you'll be able to
-preview the candidates in the minibuffer and select them with both
-simple input and powerful regexps.
-@end ifnottex
+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.
@@ -57,31 +60,35 @@ modify this GNU manual.''
* Introduction::
* Installation::
* Getting started::
+* Key bindings::
+* Completion styles::
@detailmenu
--- The Detailed Node Listing ---
Installation
-* Installing from ELPA::
+* Installing from Emacs Package Manager::
* Installing from the Git repository::
Getting started
-* Setting up Ivy global key bindings::
-* Setting up common customizations::
-* Minibuffer bindings::
-* Completion styles::
+* Basic customization::
+
+Key bindings
+
+* Global key bindings::
+* minibuffer key bindings::
-Minibuffer bindings
+minibuffer key bindings
-* Candidate navigation keys::
-* Candidate selection keys that exit the minibuffer::
-* Candidate selection keys that don't exit the minibuffer::
-* Key bindings that change the minibuffer input::
-* Miscellaneous key bindings::
-* The mini-documentation hydra::
-* Storing the current completion session to a buffer::
+* 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
@@ -97,119 +104,118 @@ Completion styles
@node Introduction
@chapter Introduction
-Any time Emacs prompts you for a string, with several choices, Ivy
-allows you to preview and quickly select among these choices.
+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.
-The key aspects of Ivy are minimalism, simplicity, customizability and
-being discoverable.
+Ivy strives for minimalism, simplicity, customizability and
+discoverability.
@subsubheading Minimalism
-Only the minimal necessary amount of information is
-displayed in the minibuffer. Compared to the default completion,
-additionally the current number of matches is displayed before the
-prompt, and a few candidates are displayed below the input. You can
-customize @code{ivy-length} to adjust the amount of displayed candidates,
-it's 10 by default.
+Uncluttered minibuffer is minimalism. Ivy shows completion
+defaults, number of matches, and 10 candidate matches below the input
+line. Customize @verb{~ivy-length~} to adjust the number of candidate matches
+displayed in the minibuffer.
@subsubheading Simplicity
-The minibuffer area should behave as a
-@code{fundamental-mode} buffer as much as possible. For example, unlike the
-default completion, @kbd{SPC} simply inserts a space, instead of being
-bound to @code{minibuffer-complete-word}. Additionally Ivy aims to have
-simple to understand code: everything is stored in easy to examine
-global variables, and no branch-introducing custom macros are used.
+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 @verb{~fundamental-mode~} as possible. @code{SPC} inserts a
+space, for example, instead of being bound to the more complex
+@verb{~minibuffer-complete-word~}. Ivy's code uses easy-to-examine global
+variables; avoids needless complications with branch-introducing
+custom macros.
@subsubheading Customizability
-Ideally, you should be able to customize your completion session as
-much as possible, with different settings for different completions,
-if you so prefer. For example, you can add your own display function
-to that points to a selected candidate with @code{->}, instead of
-highlighting it with the @code{ivy-current-match} face. It's also possible
-to customize many commands to do different things with the selected
-candidate. For example, when describing functions with
-@code{counsel-decribe-function}, you describe the candidate with @kbd{RET}, but
-can also jump to definition with @kbd{M-o d}. While the @kbd{M-o} prefix isn't
-normally customized, you can bind any following key like @kbd{d} to do
-anything to the selected candidate. This way, it's possible to group
-several functions into one through the completion interface.
+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 @verb{~->~}, instead of highlighting the selected candidate with the
+@verb{~ivy-current-match~} face. Or take the customization of actions, say
+after the candidate function is selected. @code{RET} uses
+@verb{~counsel-describe-function~} to describe the function, whereas @code{M-o
d}
+jumps to that function's definition in the code. The @code{M-o} prefix can
+be uniformly used with characters like @code{d} to group similar actions.
@subsubheading Discoverability
-While in the minibuffer, you can press @kbd{C-o} to call
-@code{hydra-ivy/body}. This will expose a large amount of commands
-available in the minibuffer, all annotated with short docstrings.
+Ivy displays easily discoverable commands through the hydra facility.
+@code{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 @code{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
-Ivy can be installed using Emacs' package manager or manually from its
-development repository.
+Install Ivy automatically through Emacs's package manager, or manually
+from Ivy's development repository.
@menu
-* Installing from ELPA::
+* Installing from Emacs Package Manager::
* Installing from the Git repository::
@end menu
-@node Installing from ELPA
-@section Installing from ELPA
+@node Installing from Emacs Package Manager
+@section Installing from Emacs Package Manager
-If you haven't used Emacs' package manager before, you can read about
-it in the Emacs manual, see @ref{Packages,,,emacs,}.
+@code{M-x} @verb{~package-install~} @code{RET} @verb{~swiper~} @code{RET}
-Ivy is available from both GNU ELPA - the official Emacs package
-repository, and from MELPA - the most popular unofficial Emacs package
-repository.
+Ivy is installed as part of @verb{~swiper~} package. @verb{~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.
-Your Emacs should be configured to use GNU ELPA automatically. To
-also add MELPA, use this code:
+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/";) t)
+ '("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}.
+After this do @code{M-x} @verb{~package-refresh-contents~} @code{RET},
followed by
+@code{M-x} @verb{~package-install~} @code{RET} @verb{~swiper~} @code{RET}.
-There's a version difference between GELPA and MELPA. GELPA holds the
-latest stable version, while MELPA contains current hourly builds.
+For package manager details, see @ref{Packages,,,emacs,}.
@node Installing from the Git repository
@section Installing from the Git repository
-Installing from Git offers advanced users numerous advantages:
+Why install from Git?
@itemize
@item
-You don't have to wait for MELPA's hourly build to finish to receive
-an update.
+No need to wait for MELPA's hourly builds
@item
-You can update to the current version and revert to an earlier one
-whenever you want.
+Easy to revert to previous versions
@item
-You can contribute to the development of Ivy by editing the code and
-sending patches/pull requests.
+Contribute to Ivy's development; send patches; pull requests
@end itemize
@strong{Configuration steps}
-Clone the Swiper repository:
+First clone the Swiper repository:
@example
cd ~/git && git clone https://github.com/abo-abo/swiper
cd swiper && make compile
@end example
-Add this code to your init:
+Then add this to Emacs init:
@lisp
(add-to-list 'load-path "~/git/swiper/")
(require 'ivy)
@end lisp
-To update the code use:
+To update the code:
@example
git pull
@@ -219,28 +225,47 @@ make
@node Getting started
@chapter Getting started
-This section describes the most common configuration steps. First of
-all, to get Ivy completion everywhere, use:
+First enable Ivy completion everywhere:
@lisp
(ivy-mode 1)
@end lisp
-You can also toggle @code{ivy-mode} on and off with @kbd{M-x} @code{ivy-mode}.
This
-is the minimal necessary step to get Ivy working.
+Note: @verb{~ivy-mode~} can be toggled on and off with @code{M-x}
@verb{~ivy-mode~}.
@menu
-* Setting up Ivy global key bindings::
-* Setting up common customizations::
-* Minibuffer bindings::
-* Completion styles::
+* Basic customization::
@end menu
-@node Setting up Ivy global key bindings
-@section Setting up Ivy global key bindings
+@node Basic customization
+@section Basic customization
-These are the recommended mnemonic (and otherwise) key bindings:
-@subsubheading Ivy-improved versions of standard commands
+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 @verb{~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)
@@ -252,7 +277,7 @@ These are the recommended mnemonic (and otherwise) key
bindings:
(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
@end lisp
-@subsubheading Ivy-based interfaces to great shell and system tools
+@subsubheading Ivy-based interface to shell and system tools
@lisp
(global-set-key (kbd "C-c g") 'counsel-git)
@@ -261,228 +286,233 @@ These are the recommended mnemonic (and otherwise) key
bindings:
(global-set-key (kbd "C-x l") 'counsel-locate)
(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
@end lisp
-@subsubheading Other useful commands
-The @code{ivy-resume} command allows to resume the last Ivy-based
-completion.
+@subsubheading Ivy-resume and other commands
+@verb{~ivy-resume~} resumes the last Ivy-based completion.
@lisp
(global-set-key (kbd "C-c C-r") 'ivy-resume)
@end lisp
-@node Setting up common customizations
-@section Setting up common customizations
+@node minibuffer key bindings
+@section minibuffer key bindings
-Here are some basic customizations that a new user might be interested
-in, in no particular order:
+Ivy includes several minibuffer bindings, which are defined in the
+@verb{~ivy-minibuffer-map~} keymap variable. The most frequently used ones
+are described here.
-@lisp
-(setq ivy-use-virtual-buffers t)
-(setq ivy-height 10)
-(setq ivy-display-style 'fancy)
-(setq ivy-count-format "(%d/%d) ")
-@end lisp
+@verb{~swiper~} or @verb{~counsel-M-x~} add more through the @verb{~keymap~}
argument to
+@verb{~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
-You can examine them more closely by looking at the documentation of
-these variables.
+@node Key bindings for navigation
+@subsection Key bindings for navigation
-@node Minibuffer bindings
-@section Minibuffer bindings
+@itemize
+@item
+@code{C-n} (@verb{~ivy-next-line~}) select next candidate
-Most of Ivy's minibuffer bindings are defined in @code{ivy-minibuffer-map}
-keymap. Some commands, like @code{swiper} or @code{counsel-M-x} pass an
-additional keymap through the @code{keymap} argument to @code{ivy-read}. The
-additional bindings will be described in each command's section. This
-section describes the most useful default key bindings.
-@menu
-* Candidate navigation keys::
-* Candidate selection keys that exit the minibuffer::
-* Candidate selection keys that don't exit the minibuffer::
-* Key bindings that change the minibuffer input::
-* Miscellaneous key bindings::
-* The mini-documentation hydra::
-* Storing the current completion session to a buffer::
-@end menu
+@item
+@code{C-p} (@verb{~ivy-previous-line~}) selects previous candidate
-@node Candidate navigation keys
-@subsection Candidate navigation keys
+@item
+@code{M-<} (@verb{~ivy-beginning-of-buffer~}) selects the first candidate
+
+@item
+@code{M->} (@verb{~ivy-end-of-buffer~}) selects the last candidate
-The most basic navigation keys are @kbd{C-n} (@code{ivy-next-line}) and
@kbd{C-p}
-(@code{ivy-previous-line}), they select the next and the previous candidate
-respectively. By default, they don't wrap-around after reaching the
-first or the last candidate. I you'd like to change this, customize
-@code{ivy-wrap}.
+@item
+@code{C-v} (@verb{~ivy-scroll-up-command~}) scrolls up by 10 lines
-Next, @kbd{M-<} (@code{ivy-beginning-of-buffer}) and @kbd{M->}
-(@code{ivy-end-of-buffer}) will select the first and the last candidate
-respectively.
+@item
+@code{M-v} (@verb{~ivy-scroll-down-command~}) scrolls down by 10 lines
+@end itemize
-Additionally, @kbd{C-v} (@code{ivy-scroll-up-command}) and @kbd{M-v}
-(@code{ivy-scroll-down-command}) allow you to scroll by whole candidate
-screen, which has the size @code{ivy-height}, 10 by default.
+To get the wrap-around behavior of @code{C-n} and @code{C-p} to cycle past the
+last and first candidates, change the default (@verb{~ivy-wrap nil~}) to
+(@verb{~ivy-warp t~}).
-@node Candidate selection keys that exit the minibuffer
-@subsection Candidate selection keys that exit the minibuffer
+Adjust scroll size through the variable @verb{~ivy-height~}, which by default
+is set to 10.
-When you've finally selected a candidate you like, you'll want to do
-something with it. In Ivy's terms it's called "calling an action",
-which can also be combined with exiting the minibuffer and thus
-finishing completion. Note that unlike with the default completion,
-exiting the minibuffer is optional, because you might want to call an
-action or actions for several candidates and not just one.
+@node Key bindings for single selection action then exit minibuffer
+@subsection Key bindings for single selection, action, then exit minibuffer
-The most basic binding is @kbd{C-m} or @kbd{RET} (@code{ivy-done}). It calls
the
-action and exits the 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.
-The second important binding is @kbd{C-j} (@code{ivy-alt-done}). It's no
-different from @code{ivy-done}, except when completing file names. In that
-case pressing @kbd{C-j} on a directory will offer completion for that
-directory, while @kbd{C-m} will select that directory and exit the
+@code{C-m} or @code{RET} (@verb{~ivy-done~}) calls the default action and
exits the
minibuffer.
-Another binding, which may be familiar is @kbd{TAB}
-(@code{ivy-partial-or-done}). It will attempt to do partial completion:
-extend the current input as much as possible, according to the
-candidates that currently match. Pressing @kbd{TAB TAB} is equivalent to
-@kbd{C-j}.
-
-With all above bindings, the action is called for the @emph{currently
-selected} candidate. But what if the input you want isn't in the
-collection, but still matches one of the candidates? Pressing either
-@kbd{C-m}, or @kbd{C-j} would call the action for that selected candidate,
-which isn't what you wanted to do. Use @kbd{C-M-j} (@code{ivy-immediate-done})
-to call the action for @emph{the current input} instead of @emph{the current
-candidate}. Common uses of @kbd{C-M-j} are with @code{find-file} and
-@code{dired-create-directory}: the new name might match the already
-existing files or directories.
-
-The penultimate key binding from the set that exits the minibuffer is
-@kbd{M-o} (@code{ivy-dispatching-done}). In case the current completion has
-more than one action to choose from to act on the selected candidate,
-@kbd{M-o} will allow you to select and call that action. In case there's
-only one action, @kbd{M-o} does the same and @kbd{C-m}.
-
-And the final binding is @kbd{C-'} (@code{ivy-avy}).
-It allows to select a visible candidate faster than e.g. @kbd{C-n C-n C-n C-n
C-m}.
-
-@node Candidate selection keys that don't exit the minibuffer
-@subsection Candidate selection keys that don't exit the minibuffer
-
-The bindings that don't exit the minibuffer are usually constructed by
-adding the meta key to the other version.
-
-@kbd{C-M-m} (@code{ivy-call}) is the non-exiting version of @kbd{C-m}. Suppose
you
-have a @code{counsel-describe-function} completion session, you've narrowed
-the candidate list significantly, say to 5 candidates, and you want to
-describe the second and the fourth candidates. With the default
-completion you would probably describe the second candidate, then
-call @code{describe-function} again, recall history with @kbd{M-p} and edit it
-to match the forth candidate and exit once more. With Ivy, you can
-press @kbd{C-n} to select the second candidate, @kbd{C-M-m} to describe it,
-@kbd{C-n C-n} to skip to the fourth candidate and @kbd{C-m} to describe it and
-exit the minibuffer.
-
-Alternatively, you could select the second candidate with @kbd{C-m}, then
-resume completion with @code{ivy-resume}. That will bring up the completion
-session in a state as if you hadn't exited: the input will be the
-same, and the second candidate will still be selected. Then you could
-once again select the fourth one with @kbd{C-n C-n C-m}.
-
-@kbd{C-M-o} (@code{ivy-dispatching-call}) is a non-exiting version of
@kbd{M-o}.
-It might be useful for instance in @code{counsel-rhythmbox}: use @kbd{C-M-o e}
-to enqueue the selected candidate, and @kbd{C-n C-m} to play the next
-one. Here, @code{play} is the default action, and @code{enqueue} is an extra
-action bound to @kbd{e}.
-
-@kbd{C-M-n} (@code{ivy-next-line-and-call}) is a combination of @kbd{C-n} and
-@kbd{C-M-m}. @kbd{C-M-p} (@code{ivy-previous-line-and-call}) is a combination
of
-@kbd{C-p} and @kbd{C-M-m}. Both can be used to call the action many
-times. For instance to open a lot of files in the current directory
-with @code{counsel-find-file}, press and hold @kbd{C-M-n}. Same for cycling
-matches in @code{counsel-git-grep} / @code{counsel-ag} / @code{counsel-locate}.
-
-@node Key bindings that change the minibuffer input
-@subsection Key bindings that change the minibuffer input
-
-@kbd{M-p} (@code{ivy-previous-history-element}) and @kbd{M-n}
-(@code{ivy-next-history-element}) allow to cycle a command's history. A
-new entry is added to the history each time an action is called on a
-candidate. Additionally, @kbd{M-n} has a special behavior when it's the
-first command (i.e. there's no history element to scroll down to): in
-that case URL or symbol at point is inserted into the minibuffer.
-
-@kbd{M-i} (@code{ivy-insert-current}) will insert the current candidate into
-the minibuffer. It's especially useful for copying files to a
-slightly different name: press @kbd{M-i} to insert the original, modify it
-slightly and @kbd{C-m}.
-
-@kbd{M-j} (@code{ivy-yank-word}) will insert the subword at point into the
-minibuffer. This is the closest thing to @kbd{C-s C-w} with
-@code{isearch}. It's not bound to @kbd{C-w} because @kbd{C-w} calls
@code{kill-region} -
-a pretty useful editing function.
-
-@kbd{S-SPC} (@code{ivy-restrict-to-matches}) will delete all current input. In
-addition it will reset the candidates collection to the one that was
-active at the moment of calling. This allows to narrow the candidate
-list in tiers if necessary.
-
-@kbd{C-r} (@code{ivy-reverse-i-search}) works in a similar way to @kbd{C-r}
bash:
-it opens a recursive completion session with the history elements as
-candidates. Once finished, that history element is inserted into the
+@code{M-o} (@verb{~ivy-dispatching-done~}) presents all available valid actions
+from which to choose. When there is only one action available, there
+is no difference between @code{M-o} and @code{C-m}.
+
+@code{C-j} (@verb{~ivy-alt-done~}) calls the alternate action, such as
completing
+a directory name in a file list whereas @code{C-m} will select that directory
+and exit the minibuffer.
+
+Exiting the minibuffer also closes the Ivy window (as specified by
+@verb{~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.
+
+@code{TAB} (@verb{~ivy-partial-or-done~}) attempts partial completion,
extending
+current input as much as possible.
+
+@code{TAB TAB} is the same as @code{C-j}.
+
+@code{C-M-j} (@verb{~ivy-immediate-done~}) is useful when there is no match for
+the given input. Or there is an incorrect partial match. @code{C-M-j} with
+@verb{~find-file~} lists ignores the partial match and instead takes the
+current input to create a new directory with @verb{~dired-create-directory~}.
+
+@verb{~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}).
+@code{C-`} uses avy's visible jump mechanism, which can further reduce
+Ivy's line-by-line scrolling that requires multiple @code{C-n} or @code{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.
+
+@code{C-M-m} (@verb{~ivy-call~}) is the non-exiting version of the default
action,
+@code{C-m} (@verb{~ivy-done~}). Instead of closing the minibuffer,
@code{C-M-m} allows
+selecting another candidate or another action. For example, @code{C-M-m} on
+functions list invokes @verb{~describe-function~}. When combined with
@code{C-n},
+function descriptions can be invoked quickly in succession.
+
+@code{RET} exits the minibuffer.
+
+@verb{~ivy-resume~} recalls the state of the completion session just before
+its last exit. Useful after an accidental @code{C-m} (@verb{~ivy-done~}).
+
+@code{C-M-o} (@verb{~ivy-dispatching-call~}) is a non-exiting version of
@code{M-o}
+(@verb{~ivy-dispatching-done~}) that can accumulate candidates into a queue.
+For example, for playback in @verb{~counsel-rhythmbox~}, @code{C-M-o e}
en-queues
+the selected candidate, and @code{C-n C-m} plays the next one in the queue.
+
+@code{C-M-n} (@verb{~ivy-next-line-and-call~}) combines @code{C-n} and
@code{C-M-m}. Applies
+an action and moves to next line. Comes in handy when opening multiple
+files from @verb{~counsel-find-file~}, @verb{~counsel-git-grep~},
@verb{~counsel-ag~}, or
+@verb{~counsel-locate~} lists. Just hold @code{C-M-n} for rapid-fire default
+action on each successive element of the list.
+
+@code{C-M-p} (@verb{~ivy-previous-line-and-call~}) combines @code{C-p} and
@code{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
+
+@code{M-n} (@verb{~ivy-next-history-element~}) and @code{M-p}
+(@verb{~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, @code{M-n} inserts symbol (or URL) at point
+into the minibuffer.
+
+@code{M-i} (@verb{~ivy-insert-current~}) inserts the current candidate into the
+minibuffer. Useful for copying and renaming files, for example: @code{M-i}
+to insert the original file name string, edit it, and then @code{C-m} to
+complete the renaming.
+
+@code{M-j} (@verb{~ivy-yank-word~}) inserts sub-word at point into minibuffer.
This
+is similar to @code{C-s C-w} with @verb{~isearch~}. Ivy reserves @code{C-w} for
+@verb{~kill-region~}.
+
+@code{S-SPC} (@verb{~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.
+
+@code{C-r} (@verb{~ivy-reverse-i-search~}) works just like @code{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 Miscellaneous key bindings
-@subsection Miscellaneous key bindings
+@node Other key bindings
+@subsection Other key bindings
-@kbd{M-w} (@code{ivy-kill-ring-save}) will work as regular
@code{kill-ring-save}
-when the region is active, otherwise it will copy all selected
-candidates to the kill ring.
+@code{M-w} (@verb{~ivy-kill-ring-save~}) copies selected candidates to the kill
+ring; when the region is active, copies active region.
-@node The mini-documentation hydra
-@subsection The mini-documentation hydra
+@node Hydra in the minibuffer
+@subsection Hydra in the minibuffer
-@kbd{C-o} (@code{hydra-ivy/body}) is a prefix to a multitude of shortcuts. For
-example: @kbd{C-n C-n C-n C-n} is equivalent to @kbd{C-o jjjj}. When
@kbd{C-o} is
-toggled on, you can no longer enter text into the minibuffer. If you
-want to resume entering text, press @kbd{C-o} or @kbd{i}.
+@code{C-o} (@verb{~hydra-ivy/body~}) invokes Hydra menus with key shortcuts.
-It serves several purposes:
+@code{C-o} or @code{i} resumes editing.
+Hydra reduces key strokes, for example: @code{C-n C-n C-n C-n} is @code{C-o
+jjjj} in Hydra. Hydra has other benefits besides certain shorter key
+bindings:
@itemize
@item
-It can be more efficient in terms of shorter bindings.
+@code{<} and @code{>} to adjust height of minibuffer,
@item
-It contains less popular bindings, like @kbd{<} and @kbd{>} for adjusting
-the height of the minibuffer.
-
-@item
-It describes the current completion state, like the case folding and
-the current action.
+describes the current completion state, such as case folding and the
+current action.
@end itemize
-@node Storing the current completion session to a buffer
-@subsection Storing the current completion session to a buffer
+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
+
+@code{C-c C-o} (@verb{~ivy-occur~}) saves the current candidates to a new
buffer;
+the list is active in the new buffer.
-@kbd{C-c C-o} (@code{ivy-occur}) will store the current candidates into a new
-buffer. Pressing @kbd{RET} or @kbd{mouse-1} in that buffer will result in the
-appropriate action being called on the selected candidate. You can
-have as many of these buffers as you like, and they will be named
-appropriately to show what they do, e.g @code{*ivy-occur
-cousnel-describe-variable "function$*}.
+@code{RET} or @code{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: @verb{~*ivy-occur counsel-describe-variable
+"function$*~}.
@node Completion styles
-@section Completion styles
+@chapter Completion styles
+
+Ivy's completion functions rely on the highly configurable regex
+builder.
-The completion in Ivy is customizable through regex builder functions.
-The default settings start out at:
+The default is:
@lisp
(setq ivy-re-builders-alist
'((t . ivy--regex-plus)))
@end lisp
-Which means that @code{ivy--regex-plus} is used for all collections. Here's
-how to use another re-builder specifically for file name completion:
+The default @verb{~ivy--regex-plus~} narrowing is always invoked unless
+specified otherwise. For example, file name completion can have its
+own custom completion function:
@lisp
(setq ivy-re-builders-alist
@@ -490,7 +520,10 @@ how to use another re-builder specifically for file name
completion:
(t . ivy--regex-plus)))
@end lisp
-These two and other styles of re-builders will be described below.
+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::
@@ -498,45 +531,61 @@ These two and other styles of re-builders will be
described below.
@end menu
@node ivy--regex-plus
-@subsection ivy--regex-plus
+@section ivy--regex-plus
+
+@verb{~ivy--regex-plus~} is Ivy's default completion method.
+
+@verb{~ivy--regex-plus~} matches by splitting the input by spaces and
+rebuilding it into a regex.
-The default completion method in Ivy is represented by the
-@code{ivy--regex-plus} function. For this function, the matching is done 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
-So "for example" is transformed into "\.*\", which
-means to match "for", followed by wildcard, followed by "example".
-You get used to how this works very fast since each part is
-highlighted with a different face in the minibuffer.
+@verbatim
+"\\(for\\).*\\(example\\)"
+@end verbatim
-If you need to match literal spaces, input that amount of spaces plus
-one, e.g. input two spaces to match one, three to match two etc.
+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.
-Regexp negation is also supported and is done by entering words that
-you don't want to match after a "!". For example "define key ! ivy
-quit" will first select everything that matches "define.*key", then
-remove everything that matches "ivy" and everything that matches
-"quit".
+As Ivy transforms typed characters into regex strings, it provides an
+intuitive feedback through font highlights.
-Other than spaces being translated into ".*" and "!" starting a
-negation group, the minibuffer input is treated as a regular regexp,
-so you can simply input things like "^", "$", "" or "[a-z]".
+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
-@subsection ivy--regex-ignore-order
+@section ivy--regex-ignore-order
-This works similarly to @code{ivy--regex-plus} except the order of the
-parts doesn't matter any more. For instance, the input "for example"
-will match "example test for".
+@verb{~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 @verb{~ivy--regex-plus~}
+normal behavior is to honor the order of regexp tokens.
@node ivy--regex-fuzzy
-@subsection ivy--regex-fuzzy
-
-This method splits each character separately, so "for" is translated
-into "f.*o.*r". This means it might result in a huge amount of
-matches. To manage this amount of matches somehow, you can install
-the @code{flx} package which will automatically be used by Ivy to do the
-candidate scoring. If you've used @code{ido-flx} before, it's almost the
-same.
+@section ivy--regex-fuzzy
+
+@verb{~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 @verb{~flx~} package's scoring mechanism, if it's
+installed.
@bye
\ No newline at end of file
