Re: Clarify `pcase' `rx' pattern doc

[Michael Heerdegen <michael_heerdegen@web.de>]

Eli Zaretskii <eliz@gnu.org> writes:


> >  (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 with `rx' REGEXPS.
>
> I don't like calling this "regexp".  Elsewhere in rx documentation we
> say either "regexps in sexp form" or just "form".  Using "regexp"
> might confuse the reader to think these are the "normal" regexp
> strings.

Wound "rx-form" be acceptable?  Also see below.

> > +`string-match'.  An error is raised if the target is not a string.
>                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Please avoid the passive tense.

I've dropped that sentence after Stefan's comment.

> > -  (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.
>
> IMO, this change is for the worse: the original clearly indicated that
> FORM is the rx-style regexp, whereas the new text blurs this
> indication.

The problem here: we usually call an expression (something to be
evaluated) a FORM.  And we have a `let' pattern in `pcase', and its
second argument is really a form.  This is super confusing and the main
reason why I didn't understand how `let' and `backref' work in this
pattern after reading the sources.  So again: is something like
"RX-FORM" acceptable, or something similar?


> > +  (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.
>
> I'd use just REF here instead of VAR-OR-NBR, which is quite a
> mouthful, and doesn't help in understanding the semantics until one
> reads the explanation.

Ok, I'll do this.


Thanks,

Michael.