[elpa] master d5489af 100/167: doc/ivy.org: Start writing a manual

[Oleh Krehel]

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

    doc/ivy.org: Start writing a manual
---
 doc/ivy.org   |  421 ++++++++++++++++++++++++++++++++++++++++++++
 doc/ivy.texi  |  542 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/style.css |  107 +++++++++++
 3 files changed, 1070 insertions(+), 0 deletions(-)

diff --git a/doc/ivy.org b/doc/ivy.org
new file mode 100644
index 0000000..a0e8fdd
--- /dev/null
+++ b/doc/ivy.org
@@ -0,0 +1,421 @@
+#+TITLE: Ivy User Manual
+#+AUTHOR: Oleh Krehel
+#+EMAIL: address@hidden
+#+DATE: 2015
+#+LANGUAGE: en
+
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Ivy: (ivy).
+#+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
+#+STARTUP: indent
+
+* Copying
+:PROPERTIES:
+:COPYING:  t
+:END:
+
+#+BEGIN_TEXINFO
address@hidden
+This manual is for Ivy 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
+
+Copyright @copyright{} 2015 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation License.''
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.''
address@hidden quotation
+#+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.
+
+The key aspects of Ivy are minimalism, simplicity, customizability and
+being discoverable.
+
+#+BEGIN_TEXINFO
address@hidden 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.
+
+#+BEGIN_TEXINFO
address@hidden 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.
+
+#+BEGIN_TEXINFO
address@hidden 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.
+
+#+BEGIN_TEXINFO
address@hidden 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.
+
+* Installation
+
+Ivy can be installed using Emacs' package manager or manually from its
+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]].
+
+Ivy is available from both GNU ELPA - the official Emacs package
+repository, and from MELPA - the most popular unofficial Emacs package
+repository.
+
+Your Emacs should be configured to use GNU ELPA automatically.  To
+also add MELPA, use this code:
+
+#+begin_src elisp
+(require 'package)
+(add-to-list 'package-archives
+             '("melpa" . "http://melpa.org/packages/";) t)
+#+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.
+
+** Installing from the Git repository
+
+Installing from Git offers advanced users numerous advantages:
+
+- 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.
+
+*Configuration steps*
+
+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:
+#+begin_src elisp
+(add-to-list 'load-path "~/git/swiper/")
+(require 'ivy)
+#+end_src
+
+To update the code use:
+#+begin_src sh
+git pull
+make
+#+end_src
+
+* Getting started
+
+This section describes the most common configuration steps.  First of
+all, to get Ivy completion everywhere, use:
+
+#+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.
+
+** Setting up Ivy global key bindings
+These are the recommended mnemonic (and otherwise) key bindings:
+#+BEGIN_TEXINFO
address@hidden Ivy-improved versions of standard commands
+#+END_TEXINFO
+#+begin_src elisp
+(global-set-key (kbd "C-s") 'swiper)
+(global-set-key (kbd "M-x") 'counsel-M-x)
+(global-set-key (kbd "C-x C-f") 'counsel-find-file)
+(global-set-key (kbd "<f1> f") 'counsel-describe-function)
+(global-set-key (kbd "<f1> v") 'counsel-describe-variable)
+(global-set-key (kbd "<f1> l") 'counsel-load-library)
+(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
+(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
+#+end_src
+#+BEGIN_TEXINFO
address@hidden Ivy-based interfaces to great shell and system tools
+#+END_TEXINFO
+#+begin_src elisp
+(global-set-key (kbd "C-c g") 'counsel-git)
+(global-set-key (kbd "C-c j") 'counsel-git-grep)
+(global-set-key (kbd "C-c k") 'counsel-ag)
+(global-set-key (kbd "C-x l") 'counsel-locate)
+(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
+#+end_src
+#+BEGIN_TEXINFO
address@hidden Other useful commands
+#+END_TEXINFO
+The =ivy-resume= command allows to resume 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
+
+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
+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~.
+
+#+BEGIN_TEXINFO
+And the final binding is @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
+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:
+#+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:
+#+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.
diff --git a/doc/ivy.texi b/doc/ivy.texi
new file mode 100644
index 0000000..a1fe0f5
--- /dev/null
+++ b/doc/ivy.texi
@@ -0,0 +1,542 @@
+\input texinfo    @c -*- texinfo -*-
address@hidden %**start of header
address@hidden ./ivy.info
address@hidden Ivy User Manual
address@hidden UTF-8
address@hidden en
address@hidden %**end of header
+
address@hidden
address@hidden
+This manual is for Ivy 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
+
+Copyright @copyright{} 2015 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation License.''
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.''
address@hidden quotation
address@hidden copying
+
address@hidden Emacs
address@hidden
+* Ivy: (ivy).           Using Ivy for completion.
address@hidden direntry
+
address@hidden
address@hidden
address@hidden Ivy User Manual
address@hidden Oleh Krehel
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden Ivy User Manual
address@hidden
address@hidden ifnottex
+
address@hidden
+* Introduction::
+* Installation::
+* Getting started::
+
address@hidden
+--- The Detailed Node Listing ---
+
+Installation
+
+* Installing from ELPA::
+* Installing from the Git repository::
+
+Getting started
+
+* Setting up Ivy global key bindings::
+* Setting up common customizations::
+* Minibuffer bindings::
+* Completion styles::
+
+Minibuffer 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::
+
+Completion styles
+
+* ivy--regex-plus::
+* ivy--regex-ignore-order::
+* ivy--regex-fuzzy::
+
address@hidden detailmenu
address@hidden menu
+
+
+
address@hidden Introduction
address@hidden Introduction
+
+Any time Emacs prompts you for a string, with several choices, Ivy
+allows you to preview and quickly select among these choices.
+
+The key aspects of Ivy are minimalism, simplicity, customizability and
+being discoverable.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden Installation
address@hidden Installation
+
+Ivy can be installed using Emacs' package manager or manually from its
+development repository.
address@hidden
+* Installing from ELPA::
+* Installing from the Git repository::
address@hidden menu
+
address@hidden Installing from ELPA
address@hidden Installing from ELPA
+
+If you haven't used Emacs' package manager before, you can read about
+it in the Emacs manual, see @ref{Packages,,,emacs,}.
+
+Ivy is available from both GNU ELPA - the official Emacs package
+repository, and from MELPA - the most popular unofficial Emacs package
+repository.
+
+Your Emacs should be configured to use GNU ELPA automatically.  To
+also add MELPA, use this code:
+
+
address@hidden
+(require 'package)
+(add-to-list 'package-archives
+             '("melpa" . "http://melpa.org/packages/";) t)
address@hidden 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}.
+
+There's a version difference between GELPA and MELPA. GELPA holds the
+latest stable version, while MELPA contains current hourly builds.
+
address@hidden Installing from the Git repository
address@hidden Installing from the Git repository
+
+Installing from Git offers advanced users numerous advantages:
+
address@hidden
address@hidden
+You don't have to wait for MELPA's hourly build to finish to receive
+an update.
+
address@hidden
+You can update to the current version and revert to an earlier one
+whenever you want.
+
address@hidden
+You can contribute to the development of Ivy by editing the code and
+sending patches/pull requests.
address@hidden itemize
+
address@hidden steps}
+
+Clone the Swiper repository:
+
address@hidden
+cd ~/git && git clone https://github.com/abo-abo/swiper
+cd swiper && make compile
address@hidden example
+
+Add this code to your init:
+
address@hidden
+(add-to-list 'load-path "~/git/swiper/")
+(require 'ivy)
address@hidden lisp
+
+To update the code use:
+
address@hidden
+git pull
+make
address@hidden example
+
address@hidden Getting started
address@hidden Getting started
+
+This section describes the most common configuration steps.  First of
+all, to get Ivy completion everywhere, use:
+
+
address@hidden
+(ivy-mode 1)
address@hidden 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.
address@hidden
+* Setting up Ivy global key bindings::
+* Setting up common customizations::
+* Minibuffer bindings::
+* Completion styles::
address@hidden menu
+
address@hidden Setting up Ivy global key bindings
address@hidden Setting up Ivy global key bindings
+
+These are the recommended mnemonic (and otherwise) key bindings:
address@hidden Ivy-improved versions of standard commands
+
address@hidden
+(global-set-key (kbd "C-s") 'swiper)
+(global-set-key (kbd "M-x") 'counsel-M-x)
+(global-set-key (kbd "C-x C-f") 'counsel-find-file)
+(global-set-key (kbd "<f1> f") 'counsel-describe-function)
+(global-set-key (kbd "<f1> v") 'counsel-describe-variable)
+(global-set-key (kbd "<f1> l") 'counsel-load-library)
+(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
+(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
address@hidden lisp
address@hidden Ivy-based interfaces to great shell and system tools
+
address@hidden
+(global-set-key (kbd "C-c g") 'counsel-git)
+(global-set-key (kbd "C-c j") 'counsel-git-grep)
+(global-set-key (kbd "C-c k") 'counsel-ag)
+(global-set-key (kbd "C-x l") 'counsel-locate)
+(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
address@hidden lisp
address@hidden Other useful commands
+The @code{ivy-resume} command allows to resume the last Ivy-based
+completion.
+
address@hidden
+(global-set-key (kbd "C-c C-r") 'ivy-resume)
address@hidden lisp
+
address@hidden Setting up common customizations
address@hidden Setting up common customizations
+
+Here are some basic customizations that a new user might be interested
+in, in no particular order:
+
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
+
+You can examine them more closely by looking at the documentation of
+these variables.
+
address@hidden Minibuffer bindings
address@hidden Minibuffer bindings
+
+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 Candidate navigation keys
address@hidden Candidate navigation keys
+
+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
+
+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.
+
+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.
+
address@hidden Candidate selection keys that exit the minibuffer
address@hidden 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 @kbd{C-m} or @kbd{RET} (@code{ivy-done}). It calls 
the
+action and exits the minibuffer.
+
+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
+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
+minibuffer.
+
address@hidden Miscellaneous key bindings
address@hidden Miscellaneous 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 The mini-documentation hydra
address@hidden The mini-documentation hydra
+
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}.
+
+It serves several purposes:
+
address@hidden
address@hidden
+It can be more efficient in terms of shorter bindings.
+
address@hidden
+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.
address@hidden itemize
+
address@hidden Storing the current completion session to a buffer
address@hidden Storing the current completion session to a 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 Completion styles
address@hidden Completion styles
+
+The completion in Ivy is customizable through regex builder functions.
+The default settings start out at:
+
address@hidden
+(setq ivy-re-builders-alist
+      '((t . ivy--regex-plus)))
address@hidden 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:
+
address@hidden
+(setq ivy-re-builders-alist
+      '((read-file-name-internal . ivy--regex-fuzzy)
+        (t . ivy--regex-plus)))
address@hidden lisp
+
+These two and other styles of re-builders will be described below.
address@hidden
+* ivy--regex-plus::
+* ivy--regex-ignore-order::
+* ivy--regex-fuzzy::
address@hidden menu
+
address@hidden ivy--regex-plus
address@hidden ivy--regex-plus
+
+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.
+
+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.
+
+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 "^", "$", "" or "[a-z]".
+
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 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
\ No newline at end of file
diff --git a/doc/style.css b/doc/style.css
new file mode 100644
index 0000000..547b4f0
--- /dev/null
+++ b/doc/style.css
@@ -0,0 +1,107 @@
+body {
+    color: #333;
+    background-color: #ffffff;
+    margin-left: 1em;
+    margin-right: auto;
+    font-family: 'Ubuntu Mono', sans-serif;
+    max-width: 50em;
+}
+
+body a {
+    color: blue;
+}
+
+h2 {
+    font-weight: normal;
+    text-indent: 0;
+    border-radius: 15px;
+    background-color: #d6d8ec;
+    text-align: left;
+    padding: 3px 3px 3px 3px;
+}
+
+h2 a[id^="unnumbered"] {
+    background-color: #d6d8ec;
+}
+
+h2 a {
+    color: white;
+    background-color:#777777;
+    font-size:18px;
+    border-radius:3px;
+    padding: 0px 5px 0px 5px; 
+}
+
+kbd {
+    padding:0.1em 0.6em;
+    border:1px solid #ccc;
+    font-size:13px;
+    font-weight:bold;
+    font-family:monospace;
+    background-color:#d6d8ec;
+    color:#333;
+    -moz-box-shadow:0 1px 0px rgba(0, 0, 0, 0.2),0 0 0 2px #ffffff inset;
+    -webkit-box-shadow:0 1px 0px rgba(0, 0, 0, 0.2),0 0 0 2px #ffffff inset;
+    box-shadow:0 1px 0px rgba(0, 0, 0, 0.2),0 0 0 2px #ffffff inset;
+    -moz-border-radius:3px;
+    -webkit-border-radius:3px;
+    border-radius:3px;
+    display:inline-block;
+    margin:0 0.1em;
+    text-shadow:0 1px 0 #fff;
+    line-height:1.4;
+    white-space:nowrap;
+}
+
+body a code {
+    color: black;
+    border: 1px solid Blue;
+    border-radius:3px;
+}
+
+code {
+    font-size:13px;
+    border: 1px solid Silver;
+    background-color: #e3e4ec;
+}
+
+pre {
+    border: 1px solid Silver;
+    background-color: #eeeeee;
+    padding: 3px;
+    margin-left: 1em;
+}
+
+cursor {
+    color: #fff;
+    background-color: #000;
+    overflow: hidden;
+}
+
+h3 {
+    counter-reset: chapter;
+}
+
+h4 {
+    margin-left: auto;
+}
+
+table, td, th {
+    border: 0px;
+}
+
+th {
+    background-color:#d6d8ec;
+}
+
+tr:nth-child(odd) {
+    background-color:#fff;
+}
+tr:nth-child(even) {
+    background-color:#d6d8ec;
+}
+
+.region {
+    color: #ffffff;
+    background-color: #f9b593;
+}