Accidentally omitted the overview! Bring it back

1 files changed, 59 insertions, 0 deletions

diff --git a/orderless.texi b/orderless.texi
index c1dc217..60ba6b6 100644
--- a/orderless.texi
+++ b/orderless.texi
@@ -25,6 +25,7 @@
 @end ifnottex
 
 @menu
+* Overview::
 * Customization::
 * Integration with other completion UIs::
 * Related packages::
@@ -59,6 +60,64 @@ Related packages
 @end detailmenu
 @end menu
 
+@node Overview
+@chapter Overview
+
+This package provides an @samp{orderless} @emph{completion style} that divides the
+pattern into space-separated components, and matches candidates that
+match all of the components in any order. Each component can match in
+any one of several ways: literally, as a regexp, as an initialism, in
+the flex style, or as multiple word prefixes. By default, regexp and
+initialism matches are enabled.
+
+A completion style is a back-end for completion and is used from a
+front-end that provides a completion UI@. Any completion style can be
+used with the default Emacs completion UI (sometimes called minibuffer
+tab completion) or with the built-in Icomplete package (which is
+similar to the more well-known Ido Mode). To use a completion style in
+this fashion simply add it as an entry in the variables
+@samp{completion-styles} or @samp{completion-category-overrides} (see their
+documentation). Note that there is also the variable
+@samp{completion-category-defaults} which configures some completion styles
+for special kinds of completion by default. If you want to use @emph{only}
+orderless, set that variable to nil.
+
+With a bit of effort, it might still be possible to use @samp{orderless} with
+other completion UIs, even if those UIs don't support the standard
+Emacs completion styles. Currently there is support for @uref{https://github.com/raxod502/selectrum, Selectrum} and
+@uref{https://github.com/abo-abo/swiper, Ivy} (see below).
+
+@lisp
+(use-package orderless
+  :ensure t
+  :init (icomplete-mode) ; optional but recommended 
+  :custom
+  (completion-styles '(orderless)) 
+  (completion-category-defaults nil)) ; optional
+@end lisp
+
+Alternatively, put @samp{orderless.el} somewhere on your @samp{load-path}, and use
+the following configuration:
+
+If you use MELPA, the easiest way to install @samp{orderless} is via
+@samp{package-install}. If you use both MELPA and @samp{use-package}, you can use:
+
+@lisp
+(require 'orderless)
+(setq completion-styles '(orderless)
+      completion-category-defaults nil) ; optional
+(icomplete-mode) ; optional but recommended
+@end lisp
+
+(And of course, if you use another completion framework such as Ivy or
+Helm, disable it.)
+
+If you like the experience of using @samp{orderless} with Icomplete, but wish
+the candidates displayed vertically, you can use @uref{https://github.com/oantolin/icomplete-vertical, icomplete-vertical},
+@uref{https://github.com/raxod502/selectrum, Selectrum} or @uref{https://github.com/abo-abo/swiper, Ivy}.
+
+Bug reports are highly welcome and appreciated!
+
 @node Customization
 @chapter Customization