Re: Clarify `pcase' `rx' pattern doc

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: address@hidden
> Date: Sat, 07 Jul 2018 15:36:04 +0200
> 
> Eli Zaretskii <address@hidden> writes:
> 
> > > > + [...]  If the target is not a string, signal an error.
> > > 
> > > We want to change that, so I think you can drop that sentence.
> >
> > Shouldn't it be dropped when that change is committed?
> 
> Then we would break documented behavior then.  What would be the gain?

Sorry, I must be confused about this.  You said "we want to change
that", so I interpreted that to mean that such a change was not yet
done and will be done shortly.  IMO, changes in documentation should
be committed together with code changes that modify the behavior
described in the documentation, thus my question.  Did I
misunderstand?

If you fear that having this sentence in the doc string will somehow
preclude us from making the code change, or make it harder, then the
doc string already says that, so if there's a problem, it is already
with us, no?

> > > But can we remove the sentence saying "Multiple occurrences of the
> > > same VAR refer to the same submatch."?  It's completely redundant
> > > IMHO.
> >
> > Is it redundant even when VAR is not a submatch number, but a symbol?
> 
> I think so.  A symbol VAR references the explicit binding created with
> (let VAR ...), i.e. a submatch, just like in the number case.

I'm just asking whether it will be immediately clear to users that any
reference to VAR refers to the same submatch.  I'm okay with removing
it if you say so.

> > Btw, in this part:
> >
> > > +  (let VAR SEXP...)  creates a new explicitly numbered submatch
> > > +                     that matches regular expressions SEXP, and
> > > +                     binds the match to VAR.
> >
> > Does "explicitly numbered" mean that VAR must be a number?  If it can
> > be something else, perhaps "explicitly named" is better?
> 
> AFAIK, in `let' VAR must be a symbol, but it seems the submatch is also
> numbered as side effect, e.g.
> 
> (pcase "Hala"
>   ((rx "H" (let x "a") (regex ".*") (backref 1)) x))
> ==> "a"

So you agree that "explicitly named" is a better wording?

> In `backref' the argument can be a number or a symbol VAR.  That's why I
> would prefer a different argument name in the docstring, "REF" maybe.  I
> had done that in my suggested patch.

I'm okay with using REF there.