From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#41006: 26.3; regular expressions documentation Date: Fri, 8 May 2020 03:10:45 -0700 Message-ID: References: <64E29F93-5A92-4F8D-9BA2-C6F14AEC2F64@acm.org> <824a1116-8e91-409f-95ff-69ef168a359d@default> <87k11s221z.fsf@stefankangas.se> <831rnukjn1.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="45497"; mail-complaints-to="usenet@ciao.gmane.io" Cc: mattiase@acm.org, 41006@debbugs.gnu.org, rtm443x@googlemail.com To: Eli Zaretskii , rms@gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 08 12:11:10 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 1jWzyI-000Bis-2T for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 08 May 2020 12:11:10 +0200 Original-Received: from localhost ([::1]:45358 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jWzyH-0003yt-5l for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 08 May 2020 06:11:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42724) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jWzyA-0003yU-BL for bug-gnu-emacs@gnu.org; Fri, 08 May 2020 06:11:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:33094) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jWzyA-0008Gd-2O for bug-gnu-emacs@gnu.org; Fri, 08 May 2020 06:11:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jWzy9-0002kf-Tg for bug-gnu-emacs@gnu.org; Fri, 08 May 2020 06:11:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 08 May 2020 10:11: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.158893265310557 (code B ref 41006); Fri, 08 May 2020 10:11:01 +0000 Original-Received: (at 41006) by debbugs.gnu.org; 8 May 2020 10:10:53 +0000 Original-Received: from localhost ([127.0.0.1]:44640 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jWzy0-0002kC-Kz for submit@debbugs.gnu.org; Fri, 08 May 2020 06:10:52 -0400 Original-Received: from mail-yb1-f173.google.com ([209.85.219.173]:44161) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jWzxz-0002js-Dr for 41006@debbugs.gnu.org; Fri, 08 May 2020 06:10:51 -0400 Original-Received: by mail-yb1-f173.google.com with SMTP id o8so653387ybc.11 for <41006@debbugs.gnu.org>; Fri, 08 May 2020 03:10:51 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:in-reply-to:references:mime-version:date :message-id:subject:to:cc:content-transfer-encoding; bh=nDYuh5G00eMvS8bAu7FbsGF5AnkqSOya7JHLdBTSULk=; b=ke+r8NYMc6KMnAzHJANxNv4BB2N8GncqK3N7lYUpHyfXbeoBBDS7TQEgDXPO/3npLT dp6bcpcrYTlCluL7J7Anp8pCKhX9Hi/0XBYbluCloXOAuPK4WtuyhIqMrRXcZ0wRoXGE 9iuPJbjoV3Mzv0+BjgBQGpfxqPsVfKbUDvUOqEeKQOBM0SpkPa4sNL6Zt+PWQ7Ot7Rip ejyMu7zlLYjCLjytUWmcqKspjD33kryz1JE//Zcm4CTXdb1B/vjBL0utLnFEweaCoy88 pFEo7fLj44fOZdj9BmdFjPY6RUs9XCBNPiKkBT8NQ9bLz4J0gTrQPOP+miy0le3pbS0e 6V6g== X-Gm-Message-State: AGi0Pua7QMYsoPqlJB+kVFkBvsaTuDluZlEyjWssCm47O5E7yQtT0bsa Hv0f7dc795AdAahyvPTzc/HtDS7hXh1jI+8ZQvw= X-Google-Smtp-Source: APiQypLWwBKarM2gEWbFUIyNvyhBlQAd8NXtrnSLswSVBS6ujA6NE3WK7tm/bLNLBCmxHz6xG4909HbYlwP9KoLXTMc= X-Received: by 2002:a25:bb08:: with SMTP id z8mr3527702ybg.129.1588932645961; Fri, 08 May 2020 03:10:45 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Fri, 8 May 2020 03:10:45 -0700 In-Reply-To: <831rnukjn1.fsf@gnu.org> 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:179917 Archived-At: Eli Zaretskii writes: >> Now we have >> >> > > * Regular Expressions:: Describing classes of strings. >> > > * Regexp Search:: Searching for a match for a regexp. >> >> We could convert Regexp Search into a subsection under Regular >> Expressions. I don't see any harm in doing that. I'm glad to hear that. > Let's first decide whether we are talking about the Emacs user manual, > the ELisp reference manual, or both. The current organization of this > stuff is slightly different in each one. The OP meant the user > manual, AFAIU. Yes, I brought up the ELisp manual. Sorry to bring this related issue into this discussion without clearly marking it as such. > To answer the specific question you asked: this is all part of a > chapter called "Searching and Replacement" in the user manual and > "Searching and Matching" in the ELisp manual. So having there a > section called "Regular Expressions" which would include a subsection > about regexp search makes less sense to me than the other way around: > have a section "Regular Expression Search" which would start with > syntax of regexps and go on to a subsection that describes the regexp > search facilities (it should then probably include the "POSIX Regexps" > section as well). I see your point here. In the user manual, perhaps we could re-organize what we have now (excluding other subsections for the sake of brevity): * Searching and Replacement ** Regexp Search:: Search for match for a regexp. ** Regexps:: Syntax of regular expressions. ** Regexp Backslash:: Regular expression constructs starting with = =E2=80=98\=E2=80=99. ** Regexp Example:: A complex regular expression explained. Into something like: * Searching and Replacement ** Regular Expression Search Search for match for a regexp. *** Regexp Syntax:: Syntax of regular expressions. *** Regexp Backslash:: Regular expression constructs starting with= =E2=80=98\=E2=80=99. *** Regexp Example:: A complex regular expression explained. I think one needs to look at it in the context of the user manual, and what the Info node `(emacs) Search' looks like to fully understand the merit of your argument. Every other subheading in that chapter is called something with " Search" (besides one, which is called "Replace"). --- In the ELisp manual, I think it could fine to have a section called simply "Regular Expressions". Either the user already knows about regexps, in which case we have no problem, or the user does not know but will soon find out. I argue this only because I find the shorter name more elegant. This is a minor stylistic point, though, and I'm fine with "Regular Expression Search" there, too. In any case, it looks like it needs a bit more work. There are actually bits and pieces about regular expressions spread out in the chapter `(elisp) Searching and Matching': * Regular Expressions:: Describing classes of strings. * Regexp Search:: Searching for a match for a regexp. * POSIX Regexps:: Searching POSIX-style for the longest match. * Match Data:: Finding out which part of the text matched, after a string or regexp search. * Search and Replace:: Commands that loop, searching and replacing. * Standard Regexps:: Useful regexps for finding sentences, pages,... Moving "Regexp Search" into a more general section called "Regular Expressions" is a step in the right direction. But then comes the problem with finding match data, which is part of the "Match Data" section, or using `re-search-forward', which is in the "Search and Replace" section. I have found all this information to be hard to find in the past. Maybe we can take a small first step here. But perhaps this section needs a bigger rethink? Best regards, Stefan Kangas