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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: mattiase <at> acm.org, rms <at> gnu.org, 41006 <at> debbugs.gnu.org, rtm443x <at> googlemail.com
Subject: bug#41006: 26.3; regular expressions documentation
Date: Fri, 08 May 2020 21:47:30 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Fri, 8 May 2020 11:17:50 -0700
> Cc: rms <at> gnu.org, mattiase <at> acm.org, 41006 <at> debbugs.gnu.org, 
> 	rtm443x <at> googlemail.com
> 
> > If the latter, then do you suggest to describe the search before
> > describing the regexps themselves?
> 
> For the user manual, I actually like that the commands are introduced
> early in `(emacs) Regexp Search', which is what users are looking for.
> Then we can explain the details of how to use them.

I think this will be suboptimal.  The chapter (or the whole manual) is
either read in its entirety (if the reader is new to the topic), or is
used as a reference.  For the former use case, we should introduce
regular expressions before we explain how to use them, otherwise the
text will be confusing (see below).  For the latter use case, the
order is entirely immaterial, since the readers are supposed to use
index-search to get directly where the subject they are looking for is
described.

IME, it sometimes helps to describe usage of something before
explaining what that something is, but only if the latter follows very
closely in the footsteps of the former.  Something like this (to take
an example of something I used just today):

  In buffers where Font Lock mode is enabled, patterns are highlighted
  using font lock.  In buffers where Font Lock mode is disabled,
  patterns are applied using overlays; in this case, the highlighting
  will not be updated as you type.  The Font Lock mode is considered
  "enabled" in a buffer if its `major-mode' causes
  `font-lock-specified-p' to return non-nil, which means the major
  mode specifies support for Font Lock.

This is not the case in the regexp search description case: there, we
will have a long list of search commands, and the reader will read all
that and all the time wonder what the heck is that "regular
expression" thing and how to write one.  When I bump into text that
doesn't explain an unusual term a sentence or two after it is first
used, I become annoyed and scan quickly forward until I find the
definition; only then I can continue reading.  My recommendation is to
avoid such "delayed" definitions.

Previous Next

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