From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#31698: 27.0; `rx' help: Show equivalent regexp constructs Date: Sun, 3 Jun 2018 10:53:29 -0700 (PDT) Message-ID: <8e6225c9-73f1-4d5c-b62e-26596d556433@default> References: <66469700-731c-4a05-a06e-51dba8dd8149@default> <83fu23dc85.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1528048327 29391 195.159.176.226 (3 Jun 2018 17:52:07 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 3 Jun 2018 17:52:07 +0000 (UTC) Cc: 31698@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jun 03 19:52:03 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fPXAg-0007X3-Tx for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Jun 2018 19:52:03 +0200 Original-Received: from localhost ([::1]:36089 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fPXCn-0003NM-OP for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Jun 2018 13:54:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54357) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fPXCh-0003NF-2M for bug-gnu-emacs@gnu.org; Sun, 03 Jun 2018 13:54:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fPXCc-0001cC-5w for bug-gnu-emacs@gnu.org; Sun, 03 Jun 2018 13:54:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:52608) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fPXCc-0001bs-1T for bug-gnu-emacs@gnu.org; Sun, 03 Jun 2018 13:54:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fPXCb-0005hE-NJ for bug-gnu-emacs@gnu.org; Sun, 03 Jun 2018 13:54: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 Jun 2018 17:54:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31698 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31698-submit@debbugs.gnu.org id=B31698.152804842121862 (code B ref 31698); Sun, 03 Jun 2018 17:54:01 +0000 Original-Received: (at 31698) by debbugs.gnu.org; 3 Jun 2018 17:53:41 +0000 Original-Received: from localhost ([127.0.0.1]:60505 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fPXCG-0005gY-Rh for submit@debbugs.gnu.org; Sun, 03 Jun 2018 13:53:41 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:59238) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fPXCE-0005gI-HS for 31698@debbugs.gnu.org; Sun, 03 Jun 2018 13:53:39 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w53HqL5g166918; Sun, 3 Jun 2018 17:53:32 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-2017-10-26; bh=YZyvPRkykM+DmCyRCcz2/eYESNLodITiBtkrqY5DZ2w=; b=s+zvkNtmpOYL1smXe5KEr+WsSBPvWVsd3KtTy+z2hMFYYt57WyrCIGhIoxPegpfHYe5C RO3HGOzA7goig6i5W5meIKClDas3/2Kmk3H2JKOdwzxadz1qV8DQfSYVotAATm6TJsbr K0J3oA+MerMWI3nDD3mqM/MjTIAwST2fGt2orZsX1RgrAGQALnlYEiE5TB+pMVZ0iE/2 FwjcbiijIsEcXHWXxkQIBTyToHnCT1LdQ6IiCp49ej7rX8DVZdVIuHiXXG2Ve1dQsd7a bXwnTFcAubb2pdteaDZfdANax1S3FBBfatv5RW+6DXC/PukTKJH1XEA0/KPCHgtxr81h Kg== Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp2120.oracle.com with ESMTP id 2jbvyp995r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 03 Jun 2018 17:53:32 +0000 Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id w53HrVDJ012535 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 3 Jun 2018 17:53:31 GMT Original-Received: from abhmp0017.oracle.com (abhmp0017.oracle.com [141.146.116.23]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id w53HrU6x021936; Sun, 3 Jun 2018 17:53:31 GMT In-Reply-To: <83fu23dc85.fsf@gnu.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4690.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8913 signatures=668702 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1805220000 definitions=main-1806030222 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:146918 Archived-At: > > Help for `rx' could use some improvement. >=20 > FWIW, I disagree. I consider the doc string of 'rx' almost perfect, > it's an example that people should learn from. >=20 > > 1. There seems to be no other help for `rx' than `C-h f rx'. Nothing > > in the Elisp manual, for instance. Perhaps it should have its own > > manual. Or perhaps it should be documented in the Elisp manual (?). > > It's hard to imagine someone trying to learn the use of `rx' just by > > looking at `C-h f rx'. Emacs should try to do better. >=20 > Given it's not-so-widespread use (and even outright critique of its > very raison d'=C3=AAtre), I see no need to describe this in the manual. = If > and when its use becomes more widespread, we could consider that. For > now, it will just bloat the manual. Perhaps its not-so-widespread use is _partly_ due to the lack of more helpful doc? I agree about the Elisp manual, FWIW. I don't agree that `rx' is adequately doc'd, at least not in terms of helping people learn it and understand the relation between its constucts and those of regular expressions. To learn to use `rx' in place of regexps (or together with regexps), the doc string is not help enough. It's fine as a doc string, but something more (e.g. an `rx' manual) would be helpful. I'm thinking, in particular, of people who are familiar with regexps (Elisp or other) but not with `rx'. =20 > > 2. Please document (in the doc string of `rx', if nowhere else) the > > correspondences between each of the `rx' constructs and regexp > > syntax. At least please document the most important ones. For > > example, `zero-or-more' presumably corresponds to postfix regexp > > char `*'. >=20 > Really? Doesn't "zero-or-more" define the effect as clearly as > possible? I think it does. Perhaps you're missing the point. Yes, `zero-or-more' describes the effect. No, it does not tell you which `rx' construct corresponds to `*' in a regexp. Again, I'm thinking, in particular, of people who are familiar with regexps (Elisp or other) but not with `rx'. Documenting the correpondence explicitly, especially for the direction regexp-construct-TO-rx-construct, would be a step toward the ability to go back and forth easier. Ideally, we'd have the ability to put your cursor on a regexp in some code and hit a key to: * see a corresponding `rx' sexp and * optionally replace the regexp with the `rx' sexp. > > 3. Please consider reordering the doc-string text to cover more > > commonly used and more important constructs before those less > > likely to be used. E.g., `not', `and', and `or', seem more > > common and more important than `category'. >=20 > "Important" is in the eyes of the beholder. I don't see why the > current order is wrong. If anything, it starts from "atoms" and moves > to "expressions", which is IMO no less important than any other > "importance" grade. OK, forget "important". You chose to ignore "more commonly used". Please consider that. You must scan 212 lines (!) of doc string before you get to `and' (aka `seq', aka `:', aka `sequence'), which tells you how to write a sequence of patterns. Again, it's not so important for a doc string, which is essentially reference doc, not help-you-learn doc. But with nothing except the doc string to go on, it takes some trudging through more rarely used stuff (I mentioned categories) just to get to stuff that is likely to be used often. > Having said all that, if someone wants to work on this and thinks they > can improve on the current state of affairs, feel free. I certainly _hope_ people feel free to help. I guess you say that to make clear that you are leaving the request open.