[elpa] externals/orderless d2891b807b 174/204: orderless+initialism example requires Marginalia (see #54)

[ELPA Syncer]

branch: externals/orderless
commit d2891b807b446c15621fb114cb813e62a360793c
Author: Omar Antolín <omar.antolin@gmail.com>
Commit: Omar Antolín <omar.antolin@gmail.com>

    orderless+initialism example requires Marginalia (see #54)
---
 README.org     | 11 +++++++++++
 orderless.texi | 20 ++++++++++++++++----
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/README.org b/README.org
index a7aff1e399..dc70d95f87 100644
--- a/README.org
+++ b/README.org
@@ -248,6 +248,17 @@ completion category.
           (symbol (styles orderless+initialism))))
 #+end_src
 
+Note that in order for the =orderless+initialism= style to kick-in with
+the above configuration, you'd need to use commands whose metadata
+indicates that the completion candidates are commands or symbols. In
+Emacs 28, =execute-extended-command= has metadata indicating you are
+selecting a command, but earlier versions of Emacs lack this metadata.
+Activating =marginalia-mode= from the 
[[https://github.com/minad/marginalia][Marginalia]] package provides this
+metadata automatically for many built-in commands and is recommended
+if you use the above example configuration, or other similarly
+fine-grained control of completion styles according to completion
+category.
+
 ** Faces for component matches
 
 The portions of a candidate matching each component get highlighted in
diff --git a/orderless.texi b/orderless.texi
index c26060e6a2..d280bd9961 100644
--- a/orderless.texi
+++ b/orderless.texi
@@ -14,6 +14,7 @@
 @finalout
 @titlepage
 @title Orderless
+@author Omar Antolín Camarena
 @end titlepage
 
 @contents
@@ -55,7 +56,7 @@ Related packages
 
 * Ivy and Helm::
 * Prescient::
-* Restricting to current matches in Icicles, Ido and Ivy: Restricting to 
current matches in Icicles Ido and Ivy.
+* Restricting to current matches in Icicles, Ido and Ivy: Restricting to 
current matches in Icicles Ido and Ivy. 
 
 @end detailmenu
 @end menu
@@ -302,6 +303,17 @@ completion category.
         (symbol (styles orderless+initialism))))
 @end lisp
 
+Note that in order for the @samp{orderless+initialism} style to kick-in with
+the above configuration, you'd need to use commands whose metadata
+indicates that the completion candidates are commands or symbols. In
+Emacs 28, @samp{execute-extended-command} has metadata indicating you are
+selecting a command, but earlier versions of Emacs lack this metadata.
+Activating @samp{marginalia-mode} from the 
@uref{https://github.com/minad/marginalia, Marginalia} package provides this
+metadata automatically for many built-in commands and is recommended
+if you use the above example configuration, or other similarly
+fine-grained control of completion styles according to completion
+category.
+
 @node Faces for component matches
 @section Faces for component matches
 
@@ -448,7 +460,7 @@ face with this configuration:
 @menu
 * Ivy and Helm::
 * Prescient::
-* Restricting to current matches in Icicles, Ido and Ivy: Restricting to 
current matches in Icicles Ido and Ivy.
+* Restricting to current matches in Icicles, Ido and Ivy: Restricting to 
current matches in Icicles Ido and Ivy. 
 @end menu
 
 @node Ivy and Helm
@@ -457,7 +469,7 @@ face with this configuration:
 The well-known and hugely powerful completion frameworks 
@uref{https://github.com/abo-abo/swiper, Ivy} and 
@uref{https://github.com/emacs-helm/helm, Helm}
 also provide for matching space-separated component regexps in any
 order. In Ivy, this is done with the @samp{ivy--regex-ignore-order} matcher.
-In Helm, it is the default, called "multi pattern matching".
+In Helm, it is the default, called ``multi pattern matching''.
 
 This package is significantly smaller than either of those because it
 solely defines a completion style, meant to be used with any completion UI 
supporting completion styles while both of those provide their own
@@ -487,7 +499,7 @@ components in any order and it can be used with either the 
@uref{https://github.
 or @uref{https://github.com/abo-abo/swiper, Ivy} completion UIs (it does not 
offer a completion-style that
 could be used with Emacs' default completion UI or with Icomplete).
 The components can be matched literally, as regexps, as initialisms or
-in the flex style (called "fuzzy" in prescient). In addition to
+in the flex style (called ``fuzzy'' in prescient). In addition to
 matching, @samp{prescient.el} also supports sorting of candidates 
(@samp{orderless}
 leaves that up to the candidate source and the completion UI).