Re: Clarify `pcase' `rx' pattern doc

[Michael Heerdegen <michael_heerdegen@web.de>]

Andreas Schwab <schwab@suse.de> writes:

> On Jun 13 2018, Michael Heerdegen <michael_heerdegen@web.de> wrote:
>
> > diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el
> > index 85e74f28ef..fa2a0898d6 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.
>
> This sentence no verb.  At least it should start with a capitalized
> word.

I can arrange that.  There is a verb, but it is elided ;-)  It is
arguable if it is not a sentence, I guess.


> What's wrong with the original version?

I found some things confusing; and some information is also missing:

The original version says "build a pcase pattern".  This text appears in
C-h f pcase, where it sounds strange.

It says it matches rx regexps, I find it more concrete to say it matches
strings using rx regexps.  It doesn't say that it raises an error if
matched against something that is not a string.

The `let' part doc speaks of a FORM where it means an rx regexp.

The `backref' part fails to say that it also accepts a positive integer
as argument, and what "backreference" actually means (is it a reference
to a pattern or to a match?).


Michael.