Clarify `pcase' `rx' pattern doc

[Michael Heerdegen <michael_heerdegen@web.de>]

[-- Attachment #1: Type: text/plain, Size: 271 bytes --]

Hello,

I had problems to understand the documentation of the `pcase' `rx'
pattern defined in "rx.el", though I'm familiar with (and user of) both
pcase and rx.  So I looked at the code and tried to tweak the docstring.
(I also removed the EXPVAL reference.)

Opinions?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Clarify-pcase-rx-pattern-documentation.patch --]
[-- Type: text/x-diff, Size: 2158 bytes --]

From 0d56315ad2470e127f5f0b464872216e7ceb6caa Mon Sep 17 00:00:00 2001
From: Michael Heerdegen <michael_heerdegen@web.de>
Date: Wed, 13 Jun 2018 01:42:34 +0200
Subject: [PATCH] Clarify `pcase' `rx' pattern documentation

---
 lisp/emacs-lisp/rx.el | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el
index 85e74f28ef..643ee6949d 100644
--- a/lisp/emacs-lisp/rx.el
+++ b/lisp/emacs-lisp/rx.el
@@ -1183,24 +1183,25 @@ rx
 
 
 (pcase-defmacro rx (&rest regexps)
-  "Build a `pcase' pattern matching `rx' regexps.
-The REGEXPS are interpreted as by `rx'.  The pattern matches if
-the regular expression so constructed matches EXPVAL, as if
-by `string-match'.
+  "`pcase' pattern matching strings using `rx' REGEXPS.
+The REGEXPS are interpreted as by `rx'.  The pattern matches any
+string matched by the regular expression so constructed, as if by
+`string-match'.
 
 In addition to the usual `rx' constructs, REGEXPS can contain the
 following constructs:
 
-  (let VAR FORM...)  creates a new explicitly numbered submatch
-                     that matches FORM and binds the match to
-                     VAR.
-  (backref VAR)      creates a backreference to the submatch
-                     introduced by a previous (let VAR ...)
-                     construct.
+  (let VAR REGEXPS...)  creates a new explicitly numbered
+                        submatch that matches the `rx' REGEXPS
+                        and binds the match to VAR.
+  (backref VAR-OR-NBR)  creates a backreference to the submatch
+                        introduced by a previous (let VAR ...)
+                        construct; VAR-OR-NBR is either a symbol
+                        VAR or a submatch number.  It matches the
+                        exact previous submatch.
 
 The VARs are associated with explicitly numbered submatches
-starting from 1.  Multiple occurrences of the same VAR refer to
-the same submatch.
+starting from 1.
 
 If a case matches, the match data is modified as usual so you can
 use it in the case body, but you still have to pass the correct
-- 
2.17.1


[-- Attachment #3: Type: text/plain, Size: 21 bytes --]



Thanks,

Michael.