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

[Drew Adams <drew.adams@oracle.com>]

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

No, I don't think it does.  The recent discussion pointed
out other reasons why it is not more widely used.  And I'm
one of those in that discussion who explicitly agreed with
those other reasons.

And FWIW I think those reasons (verbosity etc.) are more
important than the reason given in this report.  There is,
however, nothing in that discussion that argues that the
reason given here is not relevant.

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

Yes, you've made that clear.  But please "feel free" to
say it again.

I too am one such person, and guess what... 

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

Again, it's about the other direction.  Not finding out
what `zero-or-more' means or translates to in a regexp,
but finding out what `*' in a regexp translates to in `rx'.

Quick, what does a shy regexp group translate to in `rx'?
(There is no correspondence, because none is needed.)

In general, it's _not obvious_ how a given regexp would
be translated to `rx'.  It would be helpful to be able
to easily translate regexps to `rx' sexps.

The doc for `rx' could help with that by providing an
explicit mapping between the two.  Do you disagree that
that would be helpful?

The mapping exists in the code, of course, but only in
the direction rx-to-regexp.  For someone new to `rx'
who wants to analyze a regexp into its `rx' constituents,
or who wants to replace a regexp by an equivalent `rx'
sexp, documenting a regexp-to-rx mapping would help.

And (as you've said more than once) "I'm one such person."

In addition, it would be good to have a Lisp function
that performs a regexp-to-rx translation.

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

That's an argument that says only that different orders
are possible.  Unless you are trying to make the even
less useful argument that the order chosen makes no
difference.

Not everything can be stated first, clearly.  Such a
truism has no relevance for choosing which order to use.
Different orders serve different purposes.

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

Did I say you closed it?