branch: externals/orderless
commit a22d894d39003abc385d40a3fa28156a596464ca
Author: Omar Antolín <[email protected]>
Commit: Omar Antolín <[email protected]>
Revert "Update documentation" for #31
This reverts commit 4844452f4e7008da2ebe96c7dbbb7bcd655bbe68.
---
README.org | 40 ++++++++++++++++------------------------
orderless.texi | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
2 files changed, 70 insertions(+), 27 deletions(-)
diff --git a/README.org b/README.org
index a8102fe49f..847b041b77 100644
--- a/README.org
+++ b/README.org
@@ -10,7 +10,7 @@
[[https://stable.melpa.org/#/orderless][file:https://stable.melpa.org/packages/orderless-badge.svg]]
:END:
-* COMMENT Overview
+* Overview
:PROPERTIES:
:TOC: :include all :ignore this
:END:
@@ -28,45 +28,38 @@ 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
-=completion-styles= or =completion-category-overrides= (see their
-documentation). Note that there is also the variable
-=completion-category-defaults= which configures some completion styles
-for special kinds of completion by default. If you want to use /only/
-orderless, set that variable to nil.
+=completion-styles= and =completion-category-overrides= (see their
+documentation).
With a bit of effort, it might still be possible to use =orderless= with
other completion UIs, even if those UIs don't support the standard
-Emacs completion styles. Currently there is support for
[[https://github.com/raxod502/selectrum][Selectrum]] and
-[[https://github.com/abo-abo/swiper][Ivy]] (see below).
+Emacs completion styles. Currently there is support for
[[https://github.com/abo-abo/swiper][Ivy]] and
+[[https://github.com/raxod502/selectrum][Selectrum]] (see below).
+
+If you use MELPA, the easiest way to install =orderless= is via
+=package-install=. If you use both MELPA and =use-package=, you can use:
#+begin_src emacs-lisp
(use-package orderless
:ensure t
- :init (icomplete-mode) ; optional but recommended
- :custom
- (completion-styles '(orderless))
- (completion-category-defaults nil)) ; optional
+ :init (icomplete-mode) ; optional but recommended!
+ :custom (completion-styles '(orderless)))
#+end_src
Alternatively, put =orderless.el= somewhere on your =load-path=, and use
the following configuration:
-If you use MELPA, the easiest way to install =orderless= is via
-=package-install=. If you use both MELPA and =use-package=, you can use:
-
#+begin_src emacs-lisp
- (require 'orderless)
- (setq completion-styles '(orderless)
- completion-category-defaults nil) ; optional
- (icomplete-mode) ; optional but recommended
+(require 'orderless)
+(setq completion-styles '(orderless))
+(icomplete-mode) ; optional but recommended!
#+end_src
(And of course, if you use another completion framework such as Ivy or
Helm, disable it.)
If you like the experience of using =orderless= with Icomplete, but wish
-the candidates displayed vertically, you can use
[[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]],
-[[https://github.com/raxod502/selectrum][Selectrum]] or
[[https://github.com/abo-abo/swiper][Ivy]].
+the candidates displayed vertically, you can use
[[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]].
Bug reports are highly welcome and appreciated!
@@ -360,9 +353,8 @@ To use =orderless= from Ivy add this to your Ivy
configuration:
** Selectrum
-Recent versions of Selectrum use your configured completion styles by
-default! To use =orderless= from Selectrum, you can either stick to that
-default or add this to your Selectrum configuration:
+To use =orderless= from Selectrum add this to your Selectrum
+configuration:
#+begin_src emacs-lisp
(setq selectrum-refine-candidates-function #'orderless-filter)
diff --git a/orderless.texi b/orderless.texi
index c1dc217516..0aa29c6b02 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,57 @@ 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} and @samp{completion-category-overrides} (see their
+documentation).
+
+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/abo-abo/swiper, Ivy} and
+@uref{https://github.com/raxod502/selectrum, Selectrum} (see below).
+
+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
+(use-package orderless
+ :ensure t
+ :init (icomplete-mode) ; optional but recommended!
+ :custom (completion-styles '(orderless)))
+@end lisp
+
+Alternatively, put @samp{orderless.el} somewhere on your @samp{load-path}, and
use
+the following configuration:
+
+@lisp
+(require 'orderless)
+(setq completion-styles '(orderless))
+(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}.
+
+Bug reports are highly welcome and appreciated!
+
@node Customization
@chapter Customization
@@ -369,9 +421,8 @@ To use @samp{orderless} from Ivy add this to your Ivy
configuration:
@node Selectrum
@section Selectrum
-Recent versions of Selectrum use your configured completion styles by
-default! To use @samp{orderless} from Selectrum, you can either stick to that
-default or add this to your Selectrum configuration:
+To use @samp{orderless} from Selectrum add this to your Selectrum
+configuration:
@lisp
(setq selectrum-refine-candidates-function #'orderless-filter)
![https://stable.melpa.org/#/orderless][file:https://stable.melpa.org/packages/orderless-badge.svg](https://stable.melpa.org/#/orderless][file:https://stable.melpa.org/packages/orderless-badge.svg){kind=link}