GNU bug report logs - #41006
26.3; regular expressions documentation

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Richard Stallman <rms <at> gnu.org>
Cc: Mattias Engdegård <mattiase <at> acm.org>, 41006 <at> debbugs.gnu.org, rtm443x <at> googlemail.com
Subject: bug#41006: 26.3; regular expressions documentation
Date: Tue, 5 May 2020 12:42:08 -0700 (PDT)

> > IOW, separate using regexps (searching and matching)
> > from details about what regexps are and what their
> > syntax is.
> 
> This is the exact opposite of what I proposed, I think.
> 
> I argued that keeping them together would be more user-friendly and
> pedagogical.  Could you expand on why keeping them separate is better,
> in your opinion?

It's not so much about separating them physically.

1. Let users who happen to read the manual
consecutively learn about _using_ regexps before
delving into the detailed reference info about
what they are - their syntax, etc.

Which was the problem reported: you were looking
for info about how to _use_ regexps, having prior
knowledge about what regexps are and what, in
general, their syntax is.

Info about _use_ before reference info about
_what_ they are.  That's possible, and probably
more helpful.

But yes, the order between "use" (search & match)
and "what" isn't all that important, especially
since each is itself a big topic with multiple
subtopics.  The main thing is grouping like with
like, "together" - #2 (next).

2. Group all of the what-they-are info together.
POSIX etc. belongs with the reference info about
regexp syntax etc.

3. Now, as to "together" in terms of getting use
info if you happen to be (e.g. to land) in what
land: xrefs.  And vice versa: getting to what
they are from the info about using them - xrefs.

4. Putting all together physically, in one giant
node, is not feasible (especially if you include
all the other nodes about "what").  And it's not
helpful.

Just one opinion.

If you disagree, fine.  But go back to your
original problem.  You were looking for info
about how to _use_ regexps in Elisp.  And you
instead landed in the bowels of _what_ they are,
including syntax details etc.

The solution for that is (a) better or additional
indexing, and (b) possibly changing the order
(organization).  My suggestion here was for (b):
put all the "what they are" info together, and
put it under the top of the "what": `Regular
Expressions', not directly under searching and
matching.

Caveat: I haven't looked into details of what
moving this stuff around would really give.
My suggestion is to take a look and see whether
it makes sense, in particular for your use case.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.