Re: Clarify `pcase' `rx' pattern doc

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: address@hidden
> Date: Mon, 18 Jun 2018 19:22:01 +0200
> 
> > 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?

We never use rx-form in any other doc string in rx.el.  We use these:

  . regular expression FORM
  . regular expression in sexp form
  . sequence of (regular expression) forms

etc.  I think we should stick to the same nomenclature in this macro.

> > > -  (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.

As long as there's no other reference to "form" in this doc string,
the ambiguity does no harm, since you describe what FORM is right
away.  FORM and "form" are not the same thing, so the fact that 'let'
uses a "form" has no real bearing on this doc string.

> 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?

I admit really don't understand the source of your confusion.  I think
you are biased by uses of FORM in entirely unrelated contexts, which
is a mistake: the word "form" has many uses, and we shouldn't allow
the shadows of those uses to haunt us.

What other alternatives would be acceptable to you, if we exclude
RX-FORM?  Again, it's best to use something used elsewhere in the
rx.el doc strings: consistency in documentation of a feature is a Good
Thing.