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

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

> > Help for `rx' could use some improvement.
> 
> FWIW, I disagree.  I consider the doc string of 'rx' almost perfect,
> it's an example that people should learn from.
> 
> > 1. There seems to be no other help for `rx' than `C-h f rx'.  Nothing
> >    in the Elisp manual, for instance.  Perhaps it should have its own
> >    manual.  Or perhaps it should be documented in the Elisp manual (?).
> >    It's hard to imagine someone trying to learn the use of `rx' just by
> >    looking at `C-h f rx'.  Emacs should try to do better.
> 
> 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 agree about the Elisp manual, FWIW.  I don't agree that `rx'
is adequately doc'd, at least not in terms of helping people
learn it and understand the relation between its constucts
and those of regular expressions.

To learn to use `rx' in place of regexps (or together with
regexps), the doc string is not help enough.  It's fine as a
doc string, but something more (e.g. an `rx' manual) would be
helpful.

I'm thinking, in particular, of people who are familiar
with regexps (Elisp or other) but not with `rx'.
 
> > 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'.

Documenting the correpondence explicitly, especially for
the direction regexp-construct-TO-rx-construct, would be
a step toward the ability to go back and forth easier.

Ideally, we'd have the ability to put your cursor on a
regexp in some code and hit a key to:
 * see a corresponding `rx' sexp and
 * optionally replace the regexp with the `rx' sexp.

> > 3. Please consider reordering the doc-string text to cover more
> >    commonly used and more important constructs before those less
> >    likely to be used.  E.g., `not', `and', and `or', seem more
> >    common and more important than `category'.
> 
> "Important" is in the eyes of the beholder.  I don't see why the
> current order is wrong.  If anything, it starts from "atoms" and moves
> to "expressions", which is IMO no less important than any other
> "importance" grade.

OK, forget "important".  You chose to ignore "more commonly
used".  Please consider that.

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.

Again, it's not so important for a doc string, which is
essentially reference doc, not help-you-learn doc.  But
with nothing except the doc string to go on, it takes
some trudging through more rarely used stuff (I mentioned
categories) just to get to stuff that is likely to be
used often.

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