Subject: bug#41006: 26.3; regular expressions documentation

From: Stefan Kangas <[email-masked]>
Date: Sun, 03 May 2020 22:31:20 +0200

Drew Adams <[email-masked]> writes:

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

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.

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

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!  :-)

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

---

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.

Just my 2 cents here.

Best regards,
Stefan Kangas