bug#41006: 26.3; regular expressions documentation

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

> >> 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.
> 
> For me, this is different.  My background before ELisp was already
> having using regexps extensively in other languages, having read the
> "Mastering Regular Expressions" book, and so on.  (I expect that this
> is fairly typical.)

It's my case too, FWIW.  So far "this is different" isn't.

> So I go to the "Regular Expressions" node, looking mostly for how to
> use them.  But I find nothing on that there.  I only find a review of
> what looks like everything I already knew about regular expressions.

Hm.  Use of regexps is precisely what I'd have thought
you had experience with before Elisp.  What's particular
about Elisp regexps is their syntax and the behavior of
the regexp engine.  (And those pecularities are, BTW,
presented in "Mastering Regular Expressions", where
different regexp dialects are compared.)

> In the past, I did this: scratched my head, gave up and searched the
> web instead.  And it left me thinking that it's weird that Emacs
> documentation on Regular Expression is so poor...

Can you give an example (even artificial, if you don't
recall) of some "use" of regexps that you might have
wanted to find, and could not, in the manual.  Or even
just that you wanted to find (even if you found it).
I think I'm probably not getting what you have in mind.

> I have since learned that the information I have been looking for is
> actually in a separate node, for some reason not sorting under
> "Regular Expressions", called "Regexp Search".  This section is
> expertly written and exactly what I would have needed, only too bad I
> couldn't find it!  :-)

Ah, I see.  That's what you mean by using regexps.
OK, makes sense.  But that info, as you say, is there.
It's just that you couldn't find it at first.  You
didn't care about the Elisp regexp syntax etc.  You
wanted to know how to use a regexp to match text.

So the problem, I guess, was only that you had some
difficulty finding that doc.  Do you have an idea
what the difficulty was?  A guess: could it have
been because that doc was represented as being about
"searching" and you were looking for something about
"matching"?  Maybe the index could be improved, if
it's something as simple as that.

In addition, perhaps there could be a cross-reference
to the doc you were really looking for (node `Regexp
Search') from nodes `Regular Expressions' and `Regexp
Functions'.  Do you think that would help?

(Note BTW that the menu in node `Searching and
Matching' lists menu items `Regular Expressions' and
`Regexp Search'.)

> It definitely seems to me that there is room for improvement here.
> And I think it's more about the structure than content.

Got it.  Think it over and see if you can come up
with a suggested change.  I'm thinking indexing
and xrefs, but maybe something else is needed.

Maybe the order of nodes `Regular Expressions' and
`Regexp Search' should be switched: present how to
use them, before diving deep down into the exact
syntax.  I think that might make sense.

> BTW, while we're on it, it would be very handy to have an overview in
> the manual of the quirks of regexps in Emacs in comparison to other
> languages.  Mastering Regular Expressions does a very good job here,
> as far as I recall.  That plus a list of which functions to use would
> get me, when I first started out with ELisp, 99% of where I needed to
> be, I think.

That's just the comparison I mentioned above.
I'd suggest that instead of reproducing something
like that (which needs updating from time to time)
in the manual, the manual just have an external
link to such a comparison on the web.  If that
already exists then the updating might take care
of itself.  If not, then so be it.  If the book
is available as HTML, that could work.  If not,
and if there's no existing comparison, Someone(TM)
could create it on EmacsWiki.  Just a thought.