Subject: Re: bug#31698: 27.0; `rx' help: Show equivalent regexp constructs

From: Eli Zaretskii <[email-masked]>
Date: Sun, 03 Jun 2018 21:30:18 +0300

> Date: Sun, 3 Jun 2018 10:53:29 -0700 (PDT)
> From: Drew Adams <[email-masked]>
> Cc: [email-masked]
> 
> > Given it's not-so-widespread use (and even outright critique of its
> > very raison d'être), I see no need to describe this in the manual.  If
> > and when its use becomes more widespread, we could consider that.  For
> > now, it will just bloat the manual.
> 
> Perhaps its not-so-widespread use is _partly_ due to the lack
> of more helpful doc?

I very much doubt that, and the recent discussion seems to concur.

> I'm thinking, in particular, of people who are familiar
> with regexps (Elisp or other) but not with `rx'.

I'm one such person, and yet I see no problem with the current
documentation.

> > > 2. Please document (in the doc string of `rx', if nowhere else) the
> > >    correspondences between each of the `rx' constructs and regexp
> > >    syntax.  At least please document the most important ones.  For
> > >    example, `zero-or-more' presumably corresponds to postfix regexp
> > >    char `*'.
> > 
> > Really?  Doesn't "zero-or-more" define the effect as clearly as
> > possible?  I think it does.
> 
> Perhaps you're missing the point.  Yes, `zero-or-more'
> describes the effect.  No, it does not tell you which
> `rx' construct corresponds to `*' in a regexp.  Again,
> I'm thinking, in particular, of people who are familiar
> with regexps (Elisp or other) but not with `rx'.

Again, I'm one such person, and it was immediately clear to me what
'zero-or-more' translates to.

> You must scan 212 lines (!) of doc string before you get to
> `and' (aka `seq', aka `:', aka `sequence'), which tells you
> how to write a sequence of patterns.

There will always be something for which you will need to scan 212
lines before you get to it.  There isn't too much one can say on a
single line, so something's gotta give.

> > Having said all that, if someone wants to work on this and thinks they
> > can improve on the current state of affairs, feel free.
> 
> I certainly _hope_ people feel free to help.  I guess
> you say that to make clear that you are leaving the
> request open.

Did you see me close it?