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

Previous Next

Full log

Message #80 received at 41006 <at> debbugs.gnu.org (full text, mbox):

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: RE: bug#41006: 26.3; regular expressions documentation
Date: Tue, 5 May 2020 14:37:30 -0700 (PDT)

> > 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.
> 
> Thanks for explaining.  My suggestion was simply to have it all under
> one node: "Regular Expressions".  The idea being that when you go
> there, you probably also want to know how to use them.
> 
> The same goes for the index, IMHO.  But that's just how I imagine the
> manual could be improved.

That's OK too.

It was your problem - you had difficulty finding the
kind of info you were looking for - so the solution
that appeals to you most is likely the best one, at
least for addressing that particular problem.

In that case, in the section an search there'd need
to be some mention the ability to do regexp search,
and xrefs to the relevant "use" sections of the
regexp doc.

My own view favors "Every Page Is Page One"

https://everypageispageone.com/the-book/

Readers will arrive at a given part of the doc any
which way.  (In general, for doc on the web they
arrive from a search-engine search.)

With that perspective, _the_ most important thing
is to have rich, rich, rich linking among related
topics.

Very few of us will sit down and read a manual,
or even a chunk of it, in order, from beginning to
end.

That's not an argument that order/structure doesn't
matter.  It's just an argument for good linking
among related parts.

> > 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.
> 
> Agreed, my idea was to have them as subnodes.

OK by me.  Go for it, if it's OK'd.  But please be
sure that the resulting search section still ends
up useful when deprived of the regexp-search stuff.

Previous Next

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