From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#41006: 26.3; regular expressions documentation Date: Sun, 3 May 2020 18:00:48 -0700 (PDT) Message-ID: <76a4ceaa-7d50-489d-94a7-150ec14f3cd9@default> References: <64E29F93-5A92-4F8D-9BA2-C6F14AEC2F64@acm.org> <824a1116-8e91-409f-95ff-69ef168a359d@default> <87k11s221z.fsf@stefankangas.se> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="107798"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= , Richard Stallman , 41006@debbugs.gnu.org, jan To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon May 04 03:02:12 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 1jVPUp-000RwG-Dr for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 04 May 2020 03:02:11 +0200 Original-Received: from localhost ([::1]:35454 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jVPUo-00037l-FA for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 03 May 2020 21:02:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48078) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jVPUg-00035x-NY for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 21:02:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:47083) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jVPUg-0005y3-Do for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 21:02:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jVPUg-0007K3-9f for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 21:02:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 04 May 2020 01:02:02 +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.158855407225879 (code B ref 41006); Mon, 04 May 2020 01:02:02 +0000 Original-Received: (at 41006) by debbugs.gnu.org; 4 May 2020 01:01:12 +0000 Original-Received: from localhost ([127.0.0.1]:58629 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jVPTl-0006dP-H3 for submit@debbugs.gnu.org; Sun, 03 May 2020 21:01:12 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:58576) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jVPTi-0006VK-30 for 41006@debbugs.gnu.org; Sun, 03 May 2020 21:01:04 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 0440wUPk145508; Mon, 4 May 2020 01:00:54 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=zrlx80ApF8mbu17KBBjN/mXt/gCudHgyyB+VixTSYRY=; b=YQBZy2AXkO20B8gQFWEOvz3J7i2qidUJN/K6wwEmTV5R1Y4Hprwkz/hIRNMjECwG+7P7 yCi050n035gyKI8LvbFypyII9lbrpDZRP1eFY/JiSs5Vq4ERo+6NP8qt6tq7fKG9BU1D H2WJtN5pwvBzoy72A8IZKW6wijpeRRqRdgkcXPFQc+gqO6xH/XQXHUMWg7zmJp4ul3rv CbQoyfQYHpu60xHv7bXLEX2Zu6h15GJQeDju1eSGVE0BZOMArQiE7tijdjo1jvl/rVP0 x8Qzx+VdVCoPmYsz4bSt/9XX6ymhHXCfZExNyhtfJjS3I4PXzWa04S2w6xq1A9Xi4sdH aA== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2120.oracle.com with ESMTP id 30s1gmv4em-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 04 May 2020 01:00:54 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 0440uf4m149341; Mon, 4 May 2020 01:00:53 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserp3030.oracle.com with ESMTP id 30sjdpdhj3-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 04 May 2020 01:00:53 +0000 Original-Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 04410nZl014728; Mon, 4 May 2020 01:00:49 GMT In-Reply-To: <87k11s221z.fsf@stefankangas.se> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4993.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9610 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 suspectscore=0 mlxscore=0 bulkscore=0 adultscore=0 phishscore=0 mlxlogscore=999 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2005040006 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9610 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 suspectscore=0 mlxscore=0 spamscore=0 clxscore=1015 priorityscore=1501 bulkscore=0 phishscore=0 impostorscore=0 malwarescore=0 lowpriorityscore=0 mlxlogscore=999 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2005040006 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:179649 Archived-At: > >> The disposition of the regexp documentation could be improved, yes. > >> Currently it's arranged by syntax, which is the implementor's view, > >> rather than by function, which is the user's. > > > > FWIW, I disagree with that characterization. > > > > Especially when it comes to the doc for regexp > > patterns, as a user I want it to be organized > > according to syntax. A regexp (regardless of > > the particular syntax system used for regexps > > in a given language) is very much about syntax. >=20 > For me, this is different. My background before ELisp was already > having using regexps extensively in other languages, having read the > "Mastering Regular Expressions" book, and so on. (I expect that this > is fairly typical.) It's my case too, FWIW. So far "this is different" isn't. > So I go to the "Regular Expressions" node, looking mostly for how to > use them. But I find nothing on that there. I only find a review of > what looks like everything I already knew about regular expressions. Hm. Use of regexps is precisely what I'd have thought you had experience with before Elisp. What's particular about Elisp regexps is their syntax and the behavior of the regexp engine. (And those pecularities are, BTW, presented in "Mastering Regular Expressions", where different regexp dialects are compared.) > In the past, I did this: scratched my head, gave up and searched the > web instead. And it left me thinking that it's weird that Emacs > documentation on Regular Expression is so poor... Can you give an example (even artificial, if you don't recall) of some "use" of regexps that you might have wanted to find, and could not, in the manual. Or even just that you wanted to find (even if you found it). I think I'm probably not getting what you have in mind. > I have since learned that the information I have been looking for is > actually in a separate node, for some reason not sorting under > "Regular Expressions", called "Regexp Search". This section is > expertly written and exactly what I would have needed, only too bad I > couldn't find it! :-) Ah, I see. That's what you mean by using regexps. OK, makes sense. But that info, as you say, is there. It's just that you couldn't find it at first. You didn't care about the Elisp regexp syntax etc. You wanted to know how to use a regexp to match text. So the problem, I guess, was only that you had some difficulty finding that doc. Do you have an idea what the difficulty was? A guess: could it have been because that doc was represented as being about "searching" and you were looking for something about "matching"? Maybe the index could be improved, if it's something as simple as that. In addition, perhaps there could be a cross-reference to the doc you were really looking for (node `Regexp Search') from nodes `Regular Expressions' and `Regexp Functions'. Do you think that would help? (Note BTW that the menu in node `Searching and Matching' lists menu items `Regular Expressions' and `Regexp Search'.) > It definitely seems to me that there is room for improvement here. > And I think it's more about the structure than content. Got it. Think it over and see if you can come up with a suggested change. I'm thinking indexing and xrefs, but maybe something else is needed. Maybe the order of nodes `Regular Expressions' and `Regexp Search' should be switched: present how to use them, before diving deep down into the exact syntax. I think that might make sense. > BTW, while we're on it, it would be very handy to have an overview in > the manual of the quirks of regexps in Emacs in comparison to other > languages. Mastering Regular Expressions does a very good job here, > as far as I recall. That plus a list of which functions to use would > get me, when I first started out with ELisp, 99% of where I needed to > be, I think. That's just the comparison I mentioned above. I'd suggest that instead of reproducing something like that (which needs updating from time to time) in the manual, the manual just have an external link to such a comparison on the web. If that already exists then the updating might take care of itself. If not, then so be it. If the book is available as HTML, that could work. If not, and if there's no existing comparison, Someone(TM) could create it on EmacsWiki. Just a thought.