[elpa] master 1cf32c8 138/167: ivy.org manual edits

[Oleh Krehel]

branch: master
commit 1cf32c87123cbb1748835e874a81a46537112205
Author: sjLambda <address@hidden>
Commit: Oleh Krehel <address@hidden>

    ivy.org manual edits
---
 doc/ivy.org |  594 ++++++++++++++++++++++++++++++++---------------------------
 1 files changed, 318 insertions(+), 276 deletions(-)

diff --git a/doc/ivy.org b/doc/ivy.org
index a0e8fdd..28dc6e3 100644
--- a/doc/ivy.org
+++ b/doc/ivy.org
@@ -9,7 +9,7 @@
 #+TEXINFO_DIR_DESC: Using Ivy for completion.
 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css"/>
 
-#+OPTIONS: H:4 num:3 toc:2
+#+OPTIONS: H:6 num:6 toc:4
 #+STARTUP: indent
 
 * Copying
@@ -19,13 +19,16 @@
 
 #+BEGIN_TEXINFO
 @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 mini buffer. 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.
 
@@ -43,109 +46,109 @@ modify this GNU manual.''
 #+END_TEXINFO
 
 * 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.
 
 #+BEGIN_TEXINFO
 @subsubheading Minimalism
 #+END_TEXINFO
-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 =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 =ivy-length= to adjust the number of candidate matches
+displayed in the minibuffer.
 
 #+BEGIN_TEXINFO
 @subsubheading Simplicity
 #+END_TEXINFO
-The minibuffer area should behave as a
-=fundamental-mode= buffer as much as possible. For example, unlike the
-default completion, ~SPC~ simply inserts a space, instead of being
-bound to =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 =fundamental-mode= as possible. ~SPC~ inserts a
+space, for example, instead of being bound to the more complex
+=minibuffer-complete-word=. Ivy's code uses easy-to-examine global
+variables; avoids needless complications with branch-introducing
+custom macros.
 
 #+BEGIN_TEXINFO
 @subsubheading Customizability
 #+END_TEXINFO
-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 =->=, instead of
-highlighting it with the =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
-=counsel-decribe-function=, you describe the candidate with ~RET~, but
-can also jump to definition with ~M-o d~. While the ~M-o~ prefix isn't
-normally customized, you can bind any following key like ~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 =->=, instead of highlighting the selected candidate with the
+=ivy-current-match= face. Or take the customization of actions, say
+after the candidate function is selected. ~RET~ uses
+=counsel-describe-function= to describe the function, whereas ~M-o d~
+jumps to that function's definition in the code. The ~M-o~ prefix can
+be uniformly used with characters like ~d~ to group similar actions.
 
 #+BEGIN_TEXINFO
 @subsubheading Discoverability
 #+END_TEXINFO
-While in the minibuffer, you can press ~C-o~ to call
-=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.
+~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 ~C-o~ in the
+minibuffer while in the midst of the Ivy interaction. This
+discoverability minimizes exiting Ivy interface for documentation
+look-ups.
 
 * 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.
 
-** Installing from ELPA
-If you haven't used Emacs' package manager before, you can read about
-it in the Emacs manual, see [[info:emacs#Packages]].
+** Installing from Emacs Package Manager
 
-Ivy is available from both GNU ELPA - the official Emacs package
-repository, and from MELPA - the most popular unofficial Emacs package
-repository.
+~M-x~ =package-install= ~RET~ =swiper= ~RET~
 
-Your Emacs should be configured to use GNU ELPA automatically.  To
-also add MELPA, use this code:
+Ivy is installed as part of =swiper= package. =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:
 
 #+begin_src elisp
 (require 'package)
-(add-to-list 'package-archives
-             '("melpa" . "http://melpa.org/packages/";) t)
+(add-to-list 'package-archives 
+             '("melpa" . "http://melpa.org/packages/";))
 #+end_src
 
 After this do ~M-x~ =package-refresh-contents= ~RET~, followed by
 ~M-x~ =package-install= ~RET~ =swiper= ~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 [[info:emacs#Packages]].
 
 ** Installing from the Git repository
 
-Installing from Git offers advanced users numerous advantages:
+Why install from Git? 
 
-- You don't have to wait for MELPA's hourly build to finish to receive
-  an update.
-- You can update to the current version and revert to an earlier one
-  whenever you want.
-- You can contribute to the development of Ivy by editing the code and
-  sending patches/pull requests.
+- No need to wait for MELPA's hourly builds
+- Easy to revert to previous versions
+- Contribute to Ivy's development; send patches; pull requests
 
 *Configuration steps*
 
-Clone the Swiper repository:
+First clone the Swiper repository:
 #+begin_src sh
 cd ~/git && git clone https://github.com/abo-abo/swiper
 cd swiper && make compile
 #+end_src
 
-Add this code to your init:
+Then add this to Emacs init:
 #+begin_src elisp
 (add-to-list 'load-path "~/git/swiper/")
 (require 'ivy)
 #+end_src
 
-To update the code use:
+To update the code:
 #+begin_src sh
 git pull
 make
@@ -153,20 +156,32 @@ make
 
 * Getting started
 
-This section describes the most common configuration steps.  First of
-all, to get Ivy completion everywhere, use:
+First enable Ivy completion everywhere:
 
 #+begin_src elisp
 (ivy-mode 1)
 #+end_src
 
-You can also toggle =ivy-mode= on and off with ~M-x~ =ivy-mode=. This
-is the minimal necessary step to get Ivy working.
+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:
+#+begin_src elisp
+(setq ivy-use-virtual-buffers t)
+(setq ivy-height 10)
+(setq ivy-display-style 'fancy)
+(setq ivy-count-format "(%d/%d) ")
+#+end_src
+
+For additional customizations, refer to =M-x describe-variable=
+documentation.
 
-** Setting up Ivy global key bindings
-These are the recommended mnemonic (and otherwise) key bindings:
+* Key bindings
+** Global key bindings
+
+Recommended key bindings are:
 #+BEGIN_TEXINFO
address@hidden Ivy-improved versions of standard commands
address@hidden Ivy-based interface to standard commands
 #+END_TEXINFO
 #+begin_src elisp
 (global-set-key (kbd "C-s") 'swiper)
@@ -179,7 +194,7 @@ These are the recommended mnemonic (and otherwise) key 
bindings:
 (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
 #+end_src
 #+BEGIN_TEXINFO
address@hidden Ivy-based interfaces to great shell and system tools
address@hidden Ivy-based interface to shell and system tools
 #+END_TEXINFO
 #+begin_src elisp
 (global-set-key (kbd "C-c g") 'counsel-git)
@@ -189,233 +204,260 @@ These are the recommended mnemonic (and otherwise) key 
bindings:
 (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
 #+end_src
 #+BEGIN_TEXINFO
address@hidden Other useful commands
address@hidden Ivy-resume and other commands
 #+END_TEXINFO
-The =ivy-resume= command allows to resume the last Ivy-based
-completion.
+=ivy-resume= resumes the last Ivy-based completion.
 #+begin_src elisp
 (global-set-key (kbd "C-c C-r") 'ivy-resume)
 #+end_src
-** Setting up common customizations
 
-Here are some basic customizations that a new user might be interested
-in, in no particular order:
-#+begin_src elisp
-(setq ivy-use-virtual-buffers t)
-(setq ivy-height 10)
-(setq ivy-display-style 'fancy)
-(setq ivy-count-format "(%d/%d) ")
-#+end_src
+** minibuffer key bindings
 
-You can examine them more closely by looking at the documentation of
-these variables.
-
-** Minibuffer bindings
-
-Most of Ivy's minibuffer bindings are defined in =ivy-minibuffer-map=
-keymap.  Some commands, like =swiper= or =counsel-M-x= pass an
-additional keymap through the =keymap= argument to =ivy-read=.  The
-additional bindings will be described in each command's section.  This
-section describes the most useful default key bindings.
-
-*** Candidate navigation keys
-The most basic navigation keys are ~C-n~ (=ivy-next-line=) and ~C-p~
-(=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
-=ivy-wrap=.
-
-Next, ~M-<~ (=ivy-beginning-of-buffer=) and ~M->~
-(=ivy-end-of-buffer=) will select the first and the last candidate
-respectively.
-
-Additionally, ~C-v~ (=ivy-scroll-up-command=) and ~M-v~
-(=ivy-scroll-down-command=) allow you to scroll by whole candidate
-screen, which has the size =ivy-height=, 10 by default.
-
-*** Candidate selection keys that exit the minibuffer
-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.
-
-The most basic binding is ~C-m~ or ~RET~ (=ivy-done=). It calls the
-action and exits the minibuffer.
-
-The second important binding is ~C-j~ (=ivy-alt-done=). It's no
-different from =ivy-done=, except when completing file names.  In that
-case pressing ~C-j~ on a directory will offer completion for that
-directory, while ~C-m~ will select that directory and exit the
+Ivy includes several minibuffer bindings, which are defined in the
+=ivy-minibuffer-map= keymap variable. The most frequently used ones
+are described here.
+
+=swiper= or =counsel-M-x= add more through the =keymap= argument to
+=ivy-read=. These keys, also active in the minibuffer, are described
+under their respective commands.
+
+*** Key bindings for navigation
+
+- ~C-n~ (=ivy-next-line=) select next candidate
+- ~C-p~ (=ivy-previous-line=) selects previous candidate
+- ~M-<~ (=ivy-beginning-of-buffer=) selects the first candidate
+- ~M->~ (=ivy-end-of-buffer=) selects the last candidate
+- ~C-v~ (=ivy-scroll-up-command=) scrolls up by 10 lines
+- ~M-v~ (=ivy-scroll-down-command=) scrolls down by 10 lines
+
+To get the wrap-around behavior of ~C-n~ and ~C-p~ to cycle past the
+last and first candidates, change the default (=ivy-wrap nil=) to
+(=ivy-warp t=).
+
+Adjust scroll size through the variable =ivy-height=, which by default
+is set to 10.
+
+*** 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.
+
+~C-m~ or ~RET~ (=ivy-done=) calls the default action and exits the
 minibuffer.
 
-Another binding, which may be familiar is ~TAB~
-(=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 ~TAB TAB~ is equivalent to
-~C-j~.
-
-With all above bindings, the action is called for the /currently
-selected/ candidate.  But what if the input you want isn't in the
-collection, but still matches one of the candidates?  Pressing either
-~C-m~, or ~C-j~ would call the action for that selected candidate,
-which isn't what you wanted to do.  Use ~C-M-j~ (=ivy-immediate-done=)
-to call the action for /the current input/ instead of /the current
-candidate/. Common uses of ~C-M-j~ are with =find-file= and
-=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
-~M-o~ (=ivy-dispatching-done=).  In case the current completion has
-more than one action to choose from to act on the selected candidate,
-~M-o~ will allow you to select and call that action. In case there's
-only one action, ~M-o~ does the same and ~C-m~.
+~M-o~ (=ivy-dispatching-done=) presents all available valid actions
+from which to choose. When there is only one action available, there
+is no difference between ~M-o~ and ~C-m~.
+
+~C-j~ (=ivy-alt-done=) calls the alternate action, such as completing
+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
+when applying multiple actions. Multiple actions and multiple
+selections as covered in the next section of this manual.
+
+~TAB~ (=ivy-partial-or-done=) attempts partial completion, extending
+current input as much as possible.
+
+~TAB TAB~ is the same as ~C-j~.
+
+~C-M-j~ (=ivy-immediate-done=) is useful when there is no match for
+the given input. Or there is an incorrect partial match. ~C-M-j~ with
+=find-file= lists ignores the partial match and instead takes the
+current input to create a new directory with =dired-create-directory=.
+
+=ivy-immediate-done= illustrates how Ivy distinguishes between calling
+an action on the /currently selected/ candidate and calling an action
+on the /current input/.
 
 #+BEGIN_TEXINFO
-And the final binding is @kbd{C-'} (@code{ivy-avy}).
+Invoking avy completion with @kbd{C-'} (@code{ivy-avy}).
 #+END_TEXINFO
-It allows to select a visible candidate faster than e.g. ~C-n C-n C-n C-n C-m~.
-
-*** 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.
-
-~C-M-m~ (=ivy-call=) is the non-exiting version of ~C-m~. Suppose you
-have a =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 =describe-function= again, recall history with ~M-p~ and edit it
-to match the forth candidate and exit once more. With Ivy, you can
-press ~C-n~ to select the second candidate, ~C-M-m~ to describe it,
-~C-n C-n~ to skip to the fourth candidate and ~C-m~ to describe it and
-exit the minibuffer.
-
-Alternatively, you could select the second candidate with ~C-m~, then
-resume completion with =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 ~C-n C-n C-m~.
-
-~C-M-o~ (=ivy-dispatching-call=) is a non-exiting version of ~M-o~.
-It might be useful for instance in =counsel-rhythmbox=: use ~C-M-o e~
-to enqueue the selected candidate, and ~C-n C-m~ to play the next
-one. Here, =play= is the default action, and =enqueue= is an extra
-action bound to ~e~.
-
-~C-M-n~ (=ivy-next-line-and-call=) is a combination of ~C-n~ and
-~C-M-m~.  ~C-M-p~ (=ivy-previous-line-and-call=) is a combination of
-~C-p~ and ~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 =counsel-find-file=, press and hold ~C-M-n~.  Same for cycling
-matches in =counsel-git-grep= / =counsel-ag= / =counsel-locate=.
-
-*** Key bindings that change the minibuffer input
-~M-p~ (=ivy-previous-history-element=) and ~M-n~
-(=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, ~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.
-
-~M-i~ (=ivy-insert-current=) will insert the current candidate into
-the minibuffer.  It's especially useful for copying files to a
-slightly different name: press ~M-i~ to insert the original, modify it
-slightly and ~C-m~.
-
-~M-j~ (=ivy-yank-word=) will insert the subword at point into the
-minibuffer.  This is the closest thing to ~C-s C-w~ with
-=isearch=. It's not bound to ~C-w~ because ~C-w~ calls =kill-region= -
-a pretty useful editing function.
-
-~S-SPC~ (=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.
-
-~C-r~ (=ivy-reverse-i-search=) works in a similar way to ~C-r~ bash:
-it opens a recursive completion session with the history elements as
-candidates. Once finished, that history element is inserted into the
+~C-`~ uses avy's visible jump mechanism, which can further reduce
+Ivy's line-by-line scrolling that requires multiple ~C-n~ or ~C-p~
+keystrokes.
+
+*** 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. 
+
+~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. 
+
+~RET~ exists the minibuffer.
+
+=ivy-resume= recalls the state of the completion session just before
+its last exit. Useful after an accidental ~C-m~ (=ivy-done=).
+
+~C-M-o~ (=ivy-dispatching-call=) is a non-exiting version of ~M-o~
+(=ivy-dispatching-done=) that can accumulate candidates into a queue.
+For example, for playback in =counsel-rhythmbox=, ~C-M-o e~ en-queues
+the selected candidate, and ~C-n C-m~ plays the next one in the queue.
+
+~C-M-n~ (=ivy-next-line-and-call=) combines ~C-n~ and ~C-M-m~. Applies
+an action and moves to next line. Comes in handy when opening multiple
+files from =counsel-find-file=, =counsel-git-grep=, =counsel-ag=, or
+=counsel-locate= lists. Just hold ~C-M-n~ for rapid-fire default
+action on each successive element of the list.
+
+~C-M-p~ (=ivy-previous-line-and-call=) combines ~C-p~ and ~C-M-m~. Is
+the same as above except that it moves through the list in the other
+direction.
+
+*** Key bindings that alter minibuffer input
+
+~M-n~ (=ivy-next-history-element=) and ~M-p~
+(=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.
+
+~M-i~ (=ivy-insert-current=) inserts current candidate into
+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.
+
+~M-j~ (=ivy-yank-word=) inserts sub-word at point into minibuffer. This
+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.
+
+~C-r~ (=ivy-reverse-i-search=) works just like ~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.
 
-*** Miscellaneous key bindings
-~M-w~ (=ivy-kill-ring-save=) will work as regular =kill-ring-save=
-when the region is active, otherwise it will copy all selected
-candidates to the kill ring.
-
-*** The mini-documentation hydra
-~C-o~ (=hydra-ivy/body=) is a prefix to a multitude of shortcuts.  For
-example: ~C-n C-n C-n C-n~ is equivalent to ~C-o jjjj~.  When ~C-o~ is
-toggled on, you can no longer enter text into the minibuffer. If you
-want to resume entering text, press ~C-o~ or ~i~.
-
-It serves several purposes:
-
-- It can be more efficient in terms of shorter bindings.
-- It contains less popular bindings, like ~<~ and ~>~ for adjusting
-  the height of the minibuffer.
-- It describes the current completion state, like the case folding and
-  the current action.
-
-*** Storing the current completion session to a buffer
-~C-c C-o~ (=ivy-occur=) will store the current candidates into a new
-buffer.  Pressing ~RET~ or ~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 =*ivy-occur
-cousnel-describe-variable "function$*=.
-
-** Completion styles
-The completion in Ivy is customizable through regex builder functions.
-The default settings start out at:
+*** Other key bindings
+
+~M-w~ (=ivy-kill-ring-save=) copies selected candidates to the kill
+ring; when no candidates, copies active region.
+
+*** Hydra in the minibuffer
+
+~C-o~ (=hydra-ivy/body=) invokes Hydra menus with key shortcuts.
+
+~C-o~ or ~i~ resumes editing.
+
+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
+- describes the current completion state, such as case folding and the
+  current action
+
+minibuffer editing is disabled when Hydra is active.
+
+*** Saving to buffer 
+
+~C-c C-o~ (=ivy-occur=) saves 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. 
+
+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: =*ivy-occur counsel-describe-variable
+"function$*=.
+
+* Completion styles
+
+Ivy's completion functions rely on the highly configurable regex
+builder.
+
+The default is: 
 #+begin_src elisp
 (setq ivy-re-builders-alist
       '((t . ivy--regex-plus)))
 #+end_src
 
-Which means that =ivy--regex-plus= is used for all collections. Here's
-how to use another re-builder specifically for file name completion:
+The default =ivy--regex-plus= narrowing is always invoked unless
+specified otherwise. For example, file name completion can have its
+own custom completion function:
 #+begin_src elisp
 (setq ivy-re-builders-alist
       '((read-file-name-internal . ivy--regex-fuzzy)
         (t . ivy--regex-plus)))
 #+end_src
 
-These two and other styles of re-builders will be described below.
-
-*** ivy--regex-plus
-The default completion method in Ivy is represented by the
-=ivy--regex-plus= function. For this function, the matching is done by
-splitting the input by spaces and rebuilding it into a regex.
-
-So "for example" is transformed into "\\(for\\).*\\(example\\)", 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.
-
-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.
-
-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".
-
-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 "^", "$", "\b" or "[a-z]".
-
-*** ivy--regex-ignore-order
-This works similarly to =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".
-
-*** 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 =flx= package which will automatically be used by Ivy to do the
-candidate scoring. If you've used =ido-flx= before, it's almost the
-same.
+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:
+
+** ivy--regex-plus
+
+=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 
+
+#+BEGIN_EXAMPLE
+"\\(for\\).*\\(example\\)"
+#+END_EXAMPLE
+
+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.
+
+#+BEGIN_EXAMPLE
+Standard regexp identifiers work:
+
+"^", "$", "\b" or "[a-z]"
+#+END_EXAMPLE
+
+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.
+
+** ivy--regex-ignore-order
+
+=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 =ivy--regex-plus=
+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. 
+