[elpa] master 84533bb 139/167: Minor fixes to ivy.org and export to ivy.texi

[Oleh Krehel]

branch: master
commit 84533bb7bfe482eadf24ede674df02e86a1b8d25
Author: Oleh Krehel <address@hidden>
Commit: Oleh Krehel <address@hidden>

    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.
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden, 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
address@hidden face. Or take the customization of actions, say
+after the candidate function is selected. @code{RET} uses
address@hidden 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
address@hidden/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.
address@hidden 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
 
address@hidden Installing from ELPA
address@hidden Installing from ELPA
address@hidden Installing from Emacs Package Manager
address@hidden 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,}.
address@hidden @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
address@hidden @code{package-install} @kbd{RET} @code{swiper} @kbd{RET}.
+After this do @code{M-x} @verb{~package-refresh-contents~} @code{RET}, 
followed by
address@hidden @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
 
address@hidden Setting up Ivy global key bindings
address@hidden Setting up Ivy global key bindings
address@hidden Basic customization
address@hidden Basic customization
 
-These are the recommended mnemonic (and otherwise) key bindings:
address@hidden Ivy-improved versions of standard commands
+Here are some basic settings particularly useful for new Ivy
+users:
+
address@hidden
+(setq ivy-use-virtual-buffers t)
+(setq ivy-height 10)
+(setq ivy-display-style 'fancy)
+(setq ivy-count-format "(%d/%d) ")
address@hidden lisp
+
+For additional customizations, refer to @verb{~M-x describe-variable~}
+documentation.
+
address@hidden Key bindings
address@hidden Key bindings
+
address@hidden
+* Global key bindings::
+* minibuffer key bindings::
address@hidden menu
+
address@hidden Global key bindings
address@hidden Global key bindings
+
+Recommended key bindings are:
address@hidden 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
address@hidden Ivy-based interfaces to great shell and system tools
address@hidden 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
address@hidden Other useful commands
-The @code{ivy-resume} command allows to resume the last Ivy-based
-completion.
address@hidden Ivy-resume and other commands
address@hidden resumes the last Ivy-based completion.
 
 @lisp
 (global-set-key (kbd "C-c C-r") 'ivy-resume)
 @end lisp
 
address@hidden Setting up common customizations
address@hidden Setting up common customizations
address@hidden minibuffer key bindings
address@hidden 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
address@hidden keymap variable. The most frequently used ones
+are described here.
 
address@hidden
-(setq ivy-use-virtual-buffers t)
-(setq ivy-height 10)
-(setq ivy-display-style 'fancy)
-(setq ivy-count-format "(%d/%d) ")
address@hidden lisp
address@hidden or @verb{~counsel-M-x~} add more through the @verb{~keymap~} 
argument to
address@hidden These keys, also active in the minibuffer, are described
+under their respective commands.
address@hidden
+* 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::
address@hidden menu
 
-You can examine them more closely by looking at the documentation of
-these variables.
address@hidden Key bindings for navigation
address@hidden Key bindings for navigation
 
address@hidden Minibuffer bindings
address@hidden Minibuffer bindings
address@hidden
address@hidden
address@hidden (@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.
address@hidden
-* 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::
address@hidden menu
address@hidden
address@hidden (@verb{~ivy-previous-line~}) selects previous candidate
 
address@hidden Candidate navigation keys
address@hidden Candidate navigation keys
address@hidden
address@hidden<} (@verb{~ivy-beginning-of-buffer~}) selects the first candidate
+
address@hidden
address@hidden>} (@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
address@hidden
address@hidden
address@hidden (@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.
address@hidden
address@hidden (@verb{~ivy-scroll-down-command~}) scrolls down by 10 lines
address@hidden 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~}).
 
address@hidden Candidate selection keys that exit the minibuffer
address@hidden 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.
address@hidden Key bindings for single selection action then exit minibuffer
address@hidden 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
address@hidden 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
address@hidden
-
-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
address@hidden, 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
address@hidden: the new name might match the already
-existing files or directories.
-
-The penultimate key binding from the set that exits the minibuffer is
address@hidden (@code{ivy-dispatching-done}).  In case the current completion 
has
-more than one action to choose from to act on the selected candidate,
address@hidden 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}.
-
address@hidden Candidate selection keys that don't exit the minibuffer
address@hidden 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.
-
address@hidden (@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,
address@hidden 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}.
-
address@hidden (@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}.
-
address@hidden (@code{ivy-next-line-and-call}) is a combination of @kbd{C-n} and
address@hidden  @kbd{C-M-p} (@code{ivy-previous-line-and-call}) is a 
combination of
address@hidden 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}.
-
address@hidden Key bindings that change the minibuffer input
address@hidden Key bindings that change the minibuffer input
-
address@hidden (@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.
-
address@hidden (@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}.
-
address@hidden (@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
address@hidden It's not bound to @kbd{C-w} because @kbd{C-w} calls 
@code{kill-region} -
-a pretty useful editing function.
-
address@hidden (@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.
-
address@hidden (@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
address@hidden (@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}.
+
address@hidden (@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
address@hidden). 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.
+
address@hidden (@verb{~ivy-partial-or-done~}) attempts partial completion, 
extending
+current input as much as possible.
+
address@hidden TAB} is the same as @code{C-j}.
+
address@hidden (@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
address@hidden lists ignores the partial match and instead takes the
+current input to create a new directory with @verb{~dired-create-directory~}.
+
address@hidden 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}).
address@hidden 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.
+
address@hidden Key bindings for multiple selections and actions keep minibuffer 
open
address@hidden 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.
+
address@hidden (@verb{~ivy-call~}) is the non-exiting version of the default 
action,
address@hidden (@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.
+
address@hidden exits the minibuffer.
+
address@hidden recalls the state of the completion session just before
+its last exit. Useful after an accidental @code{C-m} (@verb{~ivy-done~}).
+
address@hidden (@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.
+
address@hidden (@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
address@hidden lists. Just hold @code{C-M-n} for rapid-fire default
+action on each successive element of the list.
+
address@hidden (@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.
+
address@hidden Key bindings that alter minibuffer input
address@hidden Key bindings that alter minibuffer input
+
address@hidden (@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.
+
address@hidden (@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.
+
address@hidden (@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
address@hidden
+
address@hidden (@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.
+
address@hidden (@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.
 
address@hidden Miscellaneous key bindings
address@hidden Miscellaneous key bindings
address@hidden Other key bindings
address@hidden Other key bindings
 
address@hidden (@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.
address@hidden (@verb{~ivy-kill-ring-save~}) copies selected candidates to the 
kill
+ring; when the region is active, copies active region.
 
address@hidden The mini-documentation hydra
address@hidden The mini-documentation hydra
address@hidden Hydra in the minibuffer
address@hidden Hydra in the minibuffer
 
address@hidden (@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}.
address@hidden (@verb{~hydra-ivy/body~}) invokes Hydra menus with key shortcuts.
 
-It serves several purposes:
address@hidden 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.
address@hidden<} and @code{>} to adjust height of minibuffer,
 
 @item
-It contains less popular bindings, like @kbd{<} and @kbd{>} for adjusting
-the height of the minibuffer.
-
address@hidden
-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
 
address@hidden Storing the current completion session to a buffer
address@hidden Storing the current completion session to a buffer
+Minibuffer editing is disabled when Hydra is active.
+
address@hidden Saving the current completion session to a buffer
address@hidden Saving the current completion session to a buffer
+
address@hidden C-o} (@verb{~ivy-occur~}) saves the current candidates to a new 
buffer;
+the list is active in the new buffer.
 
address@hidden 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$*}.
address@hidden 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
address@hidden Completion styles
address@hidden 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
address@hidden ivy--regex-plus
address@hidden ivy--regex-plus
+
address@hidden is Ivy's default completion method.
+
address@hidden matches by splitting the input by spaces and
+rebuilding it into a regex.
 
-The default completion method in Ivy is represented by the
address@hidden 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.
address@hidden
+"\\(for\\).*\\(example\\)"
address@hidden 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.
+
address@hidden
+Standard regexp identifiers work:
+
+"^", "$", "\b" or "[a-z]"
address@hidden 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
address@hidden ivy--regex-ignore-order
address@hidden 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".
address@hidden 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
address@hidden 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.
address@hidden ivy--regex-fuzzy
+
address@hidden 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