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: Tue, 5 May 2020 12:42:08 -0700 (PDT) Message-ID: <3dba033f-a48b-444c-bf9c-8d31c6b41852@default> References: <64E29F93-5A92-4F8D-9BA2-C6F14AEC2F64@acm.org> <824a1116-8e91-409f-95ff-69ef168a359d@default> <87k11s221z.fsf@stefankangas.se> <032f1835-d4ca-47c7-a8bb-3f4628a820a8@default> 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="86816"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= , 41006@debbugs.gnu.org, rtm443x@googlemail.com To: Stefan Kangas , Richard Stallman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue May 05 21:43:19 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 1jW3TI-000MSg-JU for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 05 May 2020 21:43:16 +0200 Original-Received: from localhost ([::1]:39244 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jW3TH-0004xd-LF for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 05 May 2020 15:43:15 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38016) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jW3T4-0004wF-Lt for bug-gnu-emacs@gnu.org; Tue, 05 May 2020 15:43:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:54310) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jW3T4-0001qs-CC for bug-gnu-emacs@gnu.org; Tue, 05 May 2020 15:43:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jW3T4-00059m-AN for bug-gnu-emacs@gnu.org; Tue, 05 May 2020 15:43: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: Tue, 05 May 2020 19:43: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.158870774419761 (code B ref 41006); Tue, 05 May 2020 19:43:02 +0000 Original-Received: (at 41006) by debbugs.gnu.org; 5 May 2020 19:42:24 +0000 Original-Received: from localhost ([127.0.0.1]:37623 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jW3SS-00058f-H5 for submit@debbugs.gnu.org; Tue, 05 May 2020 15:42:24 -0400 Original-Received: from userp2130.oracle.com ([156.151.31.86]:56732) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jW3SQ-00058Q-2A for 41006@debbugs.gnu.org; Tue, 05 May 2020 15:42:22 -0400 Original-Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 045JbbrC015117; Tue, 5 May 2020 19:42:11 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=yXUBq8rEy9aRQK+gDDe5Om6jHffz/ihtQ1iDnh57/5o=; b=YhikCmMjcvgt1k844rJGVqTvVH82ZbA8+gtx9oLlEQqXpJPyrmlF8rdbPXvOhTJKZkJB XLJSBkh0YQkMdpVeO29mmRHTFCwh3W/Ca4lE4d8i0pGGsVGzmZkFDdOhJhc1WVd3ehmu J/DNTHEmdGytBlc2eEZRik/MGPApXY+X+RjwnwTk5geiOJfUk4DUX15bmJh2BxcwEKAx TyzL/VY12nbbLrHTq1E1wvpgvwbNfaqhs8y1OqKnkntH4Q6AS3aduzFimkbpatcIBwZ3 He4iugPo4mNu/cCjhOCAO6R6SOiPoSMwzbPv0o8LIBqY2wLiZMaGRnscZ+m/+TN6KkIf yA== Original-Received: from userp3030.oracle.com (userp3030.oracle.com [156.151.31.80]) by userp2130.oracle.com with ESMTP id 30s09r6sp3-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 05 May 2020 19:42:11 +0000 Original-Received: from pps.filterd (userp3030.oracle.com [127.0.0.1]) by userp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 045Jfk3K181198; Tue, 5 May 2020 19:42:11 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userp3030.oracle.com with ESMTP id 30t1r5tggj-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 05 May 2020 19:42:11 +0000 Original-Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 045Jg9NZ011759; Tue, 5 May 2020 19:42:09 GMT In-Reply-To: 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=9612 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 bulkscore=0 adultscore=0 suspectscore=0 spamscore=0 mlxlogscore=903 malwarescore=0 phishscore=0 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2005050150 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9612 signatures=668687 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 bulkscore=0 mlxscore=0 lowpriorityscore=0 spamscore=0 adultscore=0 clxscore=1011 suspectscore=0 priorityscore=1501 malwarescore=0 mlxlogscore=957 phishscore=0 impostorscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2005050149 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:179769 Archived-At: > > IOW, separate using regexps (searching and matching) > > from details about what regexps are and what their > > syntax is. >=20 > This is the exact opposite of what I proposed, I think. >=20 > I argued that keeping them together would be more user-friendly and > pedagogical. Could you expand on why keeping them separate is better, > in your opinion? It's not so much about separating them physically. 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. Which was the problem reported: you were looking for info about how to _use_ regexps, having prior knowledge about what regexps are and what, in general, their syntax is. Info about _use_ before reference info about _what_ they are. That's possible, and probably more helpful. But yes, the order between "use" (search & match) and "what" isn't all that important, especially since each is itself a big topic with multiple subtopics. The main thing is grouping like with like, "together" - #2 (next). 2. Group all of the what-they-are info together. POSIX etc. belongs with the reference info about regexp syntax etc. 3. Now, as to "together" in terms of getting use info if you happen to be (e.g. to land) in what land: xrefs. And vice versa: getting to what they are from the info about using them - xrefs. 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. Just one opinion. If you disagree, fine. But go back to your original problem. You were looking for info about how to _use_ regexps in Elisp. And you instead landed in the bowels of _what_ they are, including syntax details etc. The solution for that is (a) better or additional indexing, and (b) possibly changing the order (organization). My suggestion here was for (b): put all the "what they are" info together, and put it under the top of the "what": `Regular Expressions', not directly under searching and matching. Caveat: I haven't looked into details of what moving this stuff around would really give. My suggestion is to take a look and see whether it makes sense, in particular for your use case.