From 61aed3e622f90ee8ace44a84a05abc1074567b74 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Omar=20Antol=C3=ADn=20Camarena?= <omar.antolin@gmail.com>
Date: Thu, 15 Feb 2024 12:17:48 -0600
Subject: [PATCH] Document the new rx format for matching styles

---
 README.org     |  9 ++++-----
 orderless.el   | 12 ++++++------
 orderless.texi | 13 ++++++-------
 3 files changed, 16 insertions(+), 18 deletions(-)

diff --git a/README.org b/README.org
index 80b44da..661b2d2 100644
--- a/README.org
+++ b/README.org
@@ -119,9 +119,10 @@ Protesilaos Stavrou's lovely [[https://gitlab.com/protesilaos/modus-themes][modu
 ** Component matching styles
 
 Each component of a pattern can match in any of several matching
-styles. A matching style is simply a function from strings to strings
-that maps a component to a regexp to match against, so it is easy to
-define new matching styles. The predefined ones are:
+styles. A matching style is simply a function from strings to regexps,
+so it is easy to define new matching styles. The regexp returned by a
+matching style can be either a string or an s-expression in =rx= syntax.
+The predefined matching styles are:
 
 - orderless-regexp :: the component is treated as a regexp that must
   match somewhere in the candidate.
@@ -131,8 +132,6 @@ define new matching styles. The predefined ones are:
 - orderless-literal :: the component is treated as a literal string
   that must occur in the candidate.
 
-  This is just =regexp-quote=.
-
 - *orderless-without-literal* :: the component is a treated as a literal
   string that must *not* occur in the candidate.
 
diff --git a/orderless.el b/orderless.el
index 15a359b..0ff178d 100644
--- a/orderless.el
+++ b/orderless.el
@@ -114,12 +114,12 @@ or a function of a single string argument."
   "List of component matching styles.
 If this variable is nil, regexp matching is assumed.
 
-A matching style is simply a function from strings to strings
-that takes a component to a regexp to match against.  If the
-resulting regexp has no capturing groups, the entire match is
-highlighted, otherwise just the captured groups are.  Several are
-provided with this package: try customizing this variable to see
-a list of them."
+A matching style is simply a function from strings to regexps.
+The returned regexps can be either strings or s-expressions in
+`rx' syntax.  If the resulting regexp has no capturing groups,
+the entire match is highlighted, otherwise just the captured
+groups are.  Several are provided with this package: try
+customizing this variable to see a list of them."
   :type 'hook
   :options (list #'orderless-regexp
                  #'orderless-literal
diff --git a/orderless.texi b/orderless.texi
index 475dd56..8afe2e9 100644
--- a/orderless.texi
+++ b/orderless.texi
@@ -56,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
@@ -151,9 +151,10 @@ Bug reports are highly welcome and appreciated!
 @section Component matching styles
 
 Each component of a pattern can match in any of several matching
-styles. A matching style is simply a function from strings to strings
-that maps a component to a regexp to match against, so it is easy to
-define new matching styles. The predefined ones are:
+styles. A matching style is simply a function from strings to regexps,
+so it is easy to define new matching styles. The regexp returned by a
+matching style can be either a string or an s-expression in @samp{rx} syntax.
+The predefined matching styles are:
 
 @table @asis
 @item orderless-regexp
@@ -166,8 +167,6 @@ If the component is not a valid regexp, it is ignored.
 the component is treated as a literal string
 that must occur in the candidate.
 
-This is just @samp{regexp-quote}.
-
 @item @strong{orderless-without-literal}
 the component is a treated as a literal
 string that must @strong{not} occur in the candidate.
@@ -576,4 +575,4 @@ Ivy has @samp{ivy-restrict-to-matches}, bound to @samp{S-SPC}, so you can get th
 effect of out of order matching without using @samp{ivy--regex-ignore-order}.
 @end itemize
 
-@bye
+@bye
\ No newline at end of file