From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#41006: 26.3; regular expressions documentation Date: Fri, 08 May 2020 21:47:30 +0300 Message-ID: <83sggagt6l.fsf@gnu.org> References: <64E29F93-5A92-4F8D-9BA2-C6F14AEC2F64@acm.org> <824a1116-8e91-409f-95ff-69ef168a359d@default> <87k11s221z.fsf@stefankangas.se> <831rnukjn1.fsf@gnu.org> <83tv0qiupr.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="122585"; mail-complaints-to="usenet@ciao.gmane.io" Cc: mattiase@acm.org, rms@gnu.org, 41006@debbugs.gnu.org, rtm443x@googlemail.com To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 08 20:48:20 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jX82m-000Vm5-1s for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 08 May 2020 20:48:20 +0200 Original-Received: from localhost ([::1]:40582 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jX82l-0000iU-0O for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 08 May 2020 14:48:19 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38292) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jX82U-0000iA-TF for bug-gnu-emacs@gnu.org; Fri, 08 May 2020 14:48:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34766) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jX82T-00010A-TH for bug-gnu-emacs@gnu.org; Fri, 08 May 2020 14:48:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jX82T-0001aq-QT for bug-gnu-emacs@gnu.org; Fri, 08 May 2020 14:48:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 08 May 2020 18:48:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 41006 X-GNU-PR-Package: emacs Original-Received: via spool by 41006-submit@debbugs.gnu.org id=B41006.15889636786111 (code B ref 41006); Fri, 08 May 2020 18:48:01 +0000 Original-Received: (at 41006) by debbugs.gnu.org; 8 May 2020 18:47:58 +0000 Original-Received: from localhost ([127.0.0.1]:46312 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jX82P-0001aV-LK for submit@debbugs.gnu.org; Fri, 08 May 2020 14:47:57 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:35258) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jX82O-0001aB-Gb for 41006@debbugs.gnu.org; Fri, 08 May 2020 14:47:56 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:35534) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jX82I-0000yz-Sy; Fri, 08 May 2020 14:47:50 -0400 Original-Received: from [176.228.60.248] (port=1709 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jX82A-0002sG-Fg; Fri, 08 May 2020 14:47:42 -0400 In-Reply-To: (message from Stefan Kangas on Fri, 8 May 2020 11:17:50 -0700) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:179938 Archived-At: > From: Stefan Kangas > Date: Fri, 8 May 2020 11:17:50 -0700 > Cc: rms@gnu.org, mattiase@acm.org, 41006@debbugs.gnu.org, > rtm443x@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.