Re: Clarify `pcase' `rx' pattern doc

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: address@hidden
> Date: Thu, 21 Jun 2018 17:13:51 +0200
> 
> Eli Zaretskii <address@hidden> writes:
> 
> > Could you please elaborate on what you didn't like or found confusing
> > in the original text, and why?  Then perhaps I could suggest how to
> > modify the text to satisfy us both.  OK?
> 
> As I said - the second arg of `let' in the `rx' pattern is of the same
> type as the argument of `rx' - a formal regexp.  But because it is named
> differently ("FORM"), I assumed it would be something different - and
> because it is named form, I thought, well, it should be a form.
> 
> So there are two things: (1) the arguments of the `rx' macro, the `rx'
> pcase macro, and the first arg of the `let' subpattern in `rx' should
> have the same name, and (2) we need to go away from the argument name
> "REGEXP" since we agree that it's a confusing name, but it's used in
> many places, the `rx' macro among them.

How about the below?

diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el
index 30bb129..dee734c 100644
--- a/lisp/emacs-lisp/rx.el
+++ b/lisp/emacs-lisp/rx.el
@@ -1181,20 +1181,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'.
+  "Build a `pcase' pattern matching `rx' REGEXPS in sexp form.
+The REGEXPS are interpreted as in `rx'.  The pattern matches any
+string that is a match for the regular expression so constructed,
+as if by `string-match'.  If the target is not a string, signal
+an error.
 
 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.
+  (let VAR SEXP...)  creates a new explicitly numbered submatch
+                     that matches regular expressions SEXP, and
+                     binds the match to VAR.
   (backref VAR)      creates a backreference to the submatch
                      introduced by a previous (let VAR ...)
-                     construct.
+                     construct.  VAR can be the same symbol
+                     in the first argument of the corresponding
+                     (let VAR ...) construct, or it can be a
+                     submatch number.  It matches the referenced
+                     submatch.
 
 The VARs are associated with explicitly numbered submatches
 starting from 1.  Multiple occurrences of the same VAR refer to