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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 3 Jun 2018 10:01:07 -0700 (PDT)
> From: 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.

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

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

Having said all that, if someone wants to work on this and thinks they
can improve on the current state of affairs, feel free.