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 14:37:30 -0700 (PDT) Message-ID: <481d95db-c770-4c03-a7ae-bd5ee154a614@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> <3dba033f-a48b-444c-bf9c-8d31c6b41852@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="95775"; 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 23:43:11 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 1jW5LL-000Oob-38 for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 05 May 2020 23:43:11 +0200 Original-Received: from localhost ([::1]:55620 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jW5LK-0000ma-4r for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 05 May 2020 17:43:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60438) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jW5LC-0000ku-SI for bug-gnu-emacs@gnu.org; Tue, 05 May 2020 17:43:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:54486) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jW5LC-0000nd-Hg for bug-gnu-emacs@gnu.org; Tue, 05 May 2020 17:43:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jW5LC-00026C-Fy for bug-gnu-emacs@gnu.org; Tue, 05 May 2020 17: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 21: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.15887149598037 (code B ref 41006); Tue, 05 May 2020 21:43:02 +0000 Original-Received: (at 41006) by debbugs.gnu.org; 5 May 2020 21:42:39 +0000 Original-Received: from localhost ([127.0.0.1]:37799 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jW5Kp-00025Y-7Q for submit@debbugs.gnu.org; Tue, 05 May 2020 17:42:39 -0400 Original-Received: from userp2130.oracle.com ([156.151.31.86]:42842) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jW5Ko-00025N-59 for 41006@debbugs.gnu.org; Tue, 05 May 2020 17:42:38 -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 045LcAoi024968; Tue, 5 May 2020 21:42:31 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=zHlnZlqaoxKMDHXeJNA0eRT0LskAV6OuIPhV/mxNrfE=; b=VN7ErGr4NJ7QEgx/sBBZ16WKb8ddWNhNhq0ogReJAIJnXe9LD/xVLspbuNkSl3XuDmSz /jSV2E/+fYvukNYgSvaGKIQNsxakz8c/pJqroPABUFCZBFaIAqqBo+9/jCexIcx4IcvM pJwYgSIdoJxHV67UufGD/j4c69b8P3UD2zDLgcPfZk3Yw6k7ldMDEHfk35ebssxJ9bCj som0PNFM57pwPkU9iOcNntwNPoxvn5p400eLg0aWkeuYQXYA7u10YUAb86WwNmY9mZRw QyYLCsOtFlm1lqILXkskkdJo18/izV10ms9KkwIB7BPKeGlC4wYTyRkrCgCPEwypFHz0 oQ== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2130.oracle.com with ESMTP id 30s09r7923-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 05 May 2020 21:42:31 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 045LbPFr156983; Tue, 5 May 2020 21:42:30 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserp3020.oracle.com with ESMTP id 30sjnfv98j-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 05 May 2020 21:42:30 +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 045LgSvm016210; Tue, 5 May 2020 21:42:28 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 mlxscore=0 adultscore=0 phishscore=0 mlxlogscore=702 bulkscore=0 malwarescore=0 spamscore=0 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2005050166 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=1015 suspectscore=0 priorityscore=1501 malwarescore=0 mlxlogscore=756 phishscore=0 impostorscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2005050166 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:179774 Archived-At: > > 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. >=20 > Thanks for explaining. My suggestion was simply to have it all under > one node: "Regular Expressions". The idea being that when you go > there, you probably also want to know how to use them. >=20 > The same goes for the index, IMHO. But that's just how I imagine the > manual could be improved. That's OK too. It was your problem - you had difficulty finding the kind of info you were looking for - so the solution that appeals to you most is likely the best one, at least for addressing that particular problem. In that case, in the section an search there'd need to be some mention the ability to do regexp search, and xrefs to the relevant "use" sections of the regexp doc. My own view favors "Every Page Is Page One" https://everypageispageone.com/the-book/ Readers will arrive at a given part of the doc any which way. (In general, for doc on the web they arrive from a search-engine search.) With that perspective, _the_ most important thing is to have rich, rich, rich linking among related topics. Very few of us will sit down and read a manual, or even a chunk of it, in order, from beginning to end. That's not an argument that order/structure doesn't matter. It's just an argument for good linking among related parts. > > 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. >=20 > Agreed, my idea was to have them as subnodes. OK by me. Go for it, if it's OK'd. But please be sure that the resulting search section still ends up useful when deprived of the regexp-search stuff.