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 13:08:14 -0700 (PDT) Message-ID: <824a1116-8e91-409f-95ff-69ef168a359d@default> References: <64E29F93-5A92-4F8D-9BA2-C6F14AEC2F64@acm.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="104231"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Richard Stallman , 41006@debbugs.gnu.org To: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= , jan Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun May 03 22: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 1jVKxB-000R1P-Ug for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 03 May 2020 22:11:10 +0200 Original-Received: from localhost ([::1]:52906 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jVKxA-00054A-Pz for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 03 May 2020 16:11:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39914) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jVKx4-000541-7s for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 16:11:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46541) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jVKx3-0003zm-Vb for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 16:11:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jVKx3-0006lv-Ql for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 16:11:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 03 May 2020 20: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.158853663625995 (code B ref 41006); Sun, 03 May 2020 20:11:01 +0000 Original-Received: (at 41006) by debbugs.gnu.org; 3 May 2020 20:10:36 +0000 Original-Received: from localhost ([127.0.0.1]:58087 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jVKwe-0006lC-3u for submit@debbugs.gnu.org; Sun, 03 May 2020 16:10:36 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:58182) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jVKwc-0006l0-4j for 41006@debbugs.gnu.org; Sun, 03 May 2020 16:10:34 -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 043K8wn1159263; Sun, 3 May 2020 20:10:18 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=l6iH8J8LL4PQdlABvQc5IH2p5IHycGDTS7/R4Ov/27k=; b=rlfhX/ztsNVU1DA9IFPVa0oegYZAqPA257AsiFpFRvWE0sTGbY+wfqSFA7nikvUODx/7 +qXDX/jB31ZqEyZQkkBpWNwS4qkW/CdBZ+oH2WDd2dJmBX0oMuCGMPuZS45rQwcdpEIQ 4zwt0yNnsscmCVjQnRYuoHbf12Vr1s2EZ2OY7sZ6rjsph7DhPSLr6f1+MnpRjG9iC7dK 2TQXlZDrE3Hm3BLn2oh4xp0XhXzYaMq6UogQnWOjjwZ153iwHHpWMY0RX/9+494f0qIJ nsUja/xq74HO5MoaVOh8Db2Os5D3zVkxdE0XueKF/vPDCAtHNflkA9eQifNu2SVM0Lrn qA== Original-Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by userp2120.oracle.com with ESMTP id 30s1gmutnh-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 03 May 2020 20:10:18 +0000 Original-Received: from pps.filterd (userp3020.oracle.com [127.0.0.1]) by userp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 043K6VUF114440; Sun, 3 May 2020 20:08:17 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userp3020.oracle.com with ESMTP id 30sjju4dud-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 03 May 2020 20:08:17 +0000 Original-Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 043K8FE2028512; Sun, 3 May 2020 20:08:15 GMT In-Reply-To: <64E29F93-5A92-4F8D-9BA2-C6F14AEC2F64@acm.org> 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 suspectscore=0 mlxscore=0 phishscore=0 bulkscore=0 malwarescore=0 spamscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2005030178 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=1011 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-2005030178 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:179613 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. And if you try to organize the content instead by the functions performed by different regexp constructs (syntax) or their combinations, then there are a zillion, conflicting possibilities. A given such "use" organization might be perfect for user U1 when looking for help with use case C1, but it won't be so great for user U2 or even for U1 when looking for help with a different use case. That's the trouble with use-case/task-oriented doc. Everyone thinks it's a great idea: "If I just had some doc that directly addressed this particular problem...". And it is a great idea as far as it goes. But in general it is not a good way to structure doc. A set of tasks/use cases is not easily structured in a useful way for users. Searching the doc can help, but that's about it. The Elisp manual is a combination of reference doc (what) with user-guide doc (how-to). Guide doc can usefully include task help. But guide doc necessarily supplements - stands on top of - reference doc; it's no substitute for it. And when it comes to regexp doc in the Elisp manual, we need solid reference doc, first and foremost. And the best organization for it in this case is in terms of regexp syntax. That doesn't mean that we can't _also_ have some guidance (how-to) doc, which directly addresses _using_ regexps: what you can (and can't) do with them, and examples of how to make best use of them in certain cases. (Just one opinion.)