bug#41006: 26.3; regular expressions documentation

[Drew Adams]

> The disposition of the regexp documentation could be improved, yes.
> Currently it's arranged by syntax, which is the implementor's view,
> rather than by function, which is the user's.

FWIW, I disagree with that characterization.

Especially when it comes to the doc for regexp
patterns, as a user I want it to be organized
according to syntax.  A regexp (regardless of
the particular syntax system used for regexps
in a given language) is very much about syntax.

And if you try to organize the content instead
by the functions performed by different regexp
constructs (syntax) or their combinations, then
there are a zillion, conflicting possibilities.

A given such "use" organization might be perfect
for user U1 when looking for help with use case
C1, but it won't be so great for user U2 or even
for U1 when looking for help with a different use
case.

That's the trouble with use-case/task-oriented
doc.  Everyone thinks it's a great idea: "If I
just had some doc that directly addressed this
particular problem...".  And it is a great idea
as far as it goes.  But in general it is not a
good way to structure doc.  A set of tasks/use
cases is not easily structured in a useful way
for users.  Searching the doc can help, but
that's about it.

The Elisp manual is a combination of reference
doc (what) with user-guide doc (how-to).  Guide
doc can usefully include task help.  But guide
doc necessarily supplements - stands on top of -
reference doc; it's no substitute for it.

And when it comes to regexp doc in the Elisp
manual, we need solid reference doc, first and
foremost.  And the best organization for it in
this case is in terms of regexp syntax.

That doesn't mean that we can't _also_ have
some guidance (how-to) doc, which directly
addresses _using_ regexps: what you can (and
can't) do with them, and examples of how to
make best use of them in certain cases.

(Just one opinion.)