Re: Clarify `pcase' `rx' pattern doc

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: Eli Zaretskii <address@hidden>
> Date: Mon, 18 Jun 2018 14:34:50 +0200
> 
> > Opinions?
> 
> For now, I would like to install the following, slightly modified
> version (I left the first sentence unchanged so that we can care about
> that systematically in a later commit) into emacs-26.  Is that ok?

Thanks, I have a few minor comments regarding the style:

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

> +`string-match'.  An error is raised if the target is not a string.
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please avoid the passive tense.  In this case, I'd rephrase:

  If the target is not a string, this macro signals an error.

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

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

This is OK for the emacs-26 branch, once we agree on the above nits.