From 4844452f4e7008da2ebe96c7dbbb7bcd655bbe68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Omar=20Antol=C3=ADn?= Date: Mon, 18 Jan 2021 13:37:16 -0600 Subject: Update documentation 1. Mention setting completion-category-defaults to nil. 2. Update comments about Selectrum. --- README.org | 40 ++++++++++++++++++++++++---------------- orderless.texi | 57 +++------------------------------------------------------ 2 files changed, 27 insertions(+), 70 deletions(-) diff --git a/README.org b/README.org index 847b041..a8102fe 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: -* Overview +* COMMENT Overview :PROPERTIES: :TOC: :include all :ignore this :END: @@ -28,38 +28,45 @@ 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= and =completion-category-overrides= (see their -documentation). +=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. 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/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: +Emacs completion styles. Currently there is support for [[https://github.com/raxod502/selectrum][Selectrum]] and +[[https://github.com/abo-abo/swiper][Ivy]] (see below). #+begin_src emacs-lisp (use-package orderless :ensure t - :init (icomplete-mode) ; optional but recommended! - :custom (completion-styles '(orderless))) + :init (icomplete-mode) ; optional but recommended + :custom + (completion-styles '(orderless)) + (completion-category-defaults nil)) ; optional #+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)) -(icomplete-mode) ; optional but recommended! + (require 'orderless) + (setq completion-styles '(orderless) + completion-category-defaults nil) ; optional + (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]]. +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]]. Bug reports are highly welcome and appreciated! @@ -353,8 +360,9 @@ To use =orderless= from Ivy add this to your Ivy configuration: ** Selectrum -To use =orderless= from Selectrum add this to your Selectrum -configuration: +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: #+begin_src emacs-lisp (setq selectrum-refine-candidates-function #'orderless-filter) diff --git a/orderless.texi b/orderless.texi index 0aa29c6..c1dc217 100644 --- a/orderless.texi +++ b/orderless.texi @@ -25,7 +25,6 @@ @end ifnottex @menu -* Overview:: * Customization:: * Integration with other completion UIs:: * Related packages:: @@ -60,57 +59,6 @@ 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 @@ -421,8 +369,9 @@ To use @samp{orderless} from Ivy add this to your Ivy configuration: @node Selectrum @section Selectrum -To use @samp{orderless} from Selectrum add this to your Selectrum -configuration: +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: @lisp (setq selectrum-refine-candidates-function #'orderless-filter) -- cgit v1.0