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#33541: 26; Doc string of `align-regexp' Date: Wed, 28 Nov 2018 15:46:09 -0800 (PST) Message-ID: References: <8aa04dea-d34b-4d58-9671-07e6e575c54d@default> <54ba7381c515b5019d5a0322ece9b35a@webmail.orcon.net.nz> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1543448717 21899 195.159.176.226 (28 Nov 2018 23:45:17 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 28 Nov 2018 23:45:17 +0000 (UTC) Cc: 33541@debbugs.gnu.org To: Phil Sainty Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Nov 29 00:45:12 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 1gS9W2-0005Xv-Nc for geb-bug-gnu-emacs@m.gmane.org; Thu, 29 Nov 2018 00:45:11 +0100 Original-Received: from localhost ([::1]:50407 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gS9Y9-00028M-Ao for geb-bug-gnu-emacs@m.gmane.org; Wed, 28 Nov 2018 18:47:21 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43264) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gS9Y1-000283-Ns for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:47:14 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gS9Xu-0006wb-1u for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:47:11 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:49634) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gS9Xq-0006tI-8H for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:47:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gS9Xq-0003oa-0z for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:47:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 28 Nov 2018 23:47:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 33541 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 33541-submit@debbugs.gnu.org id=B33541.154344878414616 (code B ref 33541); Wed, 28 Nov 2018 23:47:01 +0000 Original-Received: (at 33541) by debbugs.gnu.org; 28 Nov 2018 23:46:24 +0000 Original-Received: from localhost ([127.0.0.1]:53892 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gS9XE-0003ng-Fw for submit@debbugs.gnu.org; Wed, 28 Nov 2018 18:46:24 -0500 Original-Received: from userp2130.oracle.com ([156.151.31.86]:53280) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gS9XC-0003nS-N2 for 33541@debbugs.gnu.org; Wed, 28 Nov 2018 18:46:23 -0500 Original-Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.22/8.16.0.22) with SMTP id wASNj85w012968; Wed, 28 Nov 2018 23:46:16 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-2018-07-02; bh=zx3bt7pmPBNpmBqTR6iLlUVu4As7cMdh10q6BGgJ/tM=; b=PH5Ajs/rCoJuJvti5ZxO7c36RzeBqcH5Q6ax3/08aphVHLdEHOkXRcD78riGaLVd6HWU Uc7gUPAvONgH1RwVgplbrnXhNU9M/O6V0Jq1PKRGGTJscjtIw7TcYIXMhTn8zbhOmy5R KGESLCEtyWEOZhHievVcTfuwbtALokZlIRm/pic6XtXzQRe1hxgu1wkmx9vlnHiW8fsQ X7R9DxckSuM8CfGs1G7TI84vozQSvFjs9XGGAiDLR6CMcL+Y5CurR0Gx1S6bLVHCkMcz /E1tT/NTG7e87GMtvzf7ObQclaOuTKdJ6MeRx78N58gk83Gxd3QdrFZ1HQ4KpaJn/nSv 1A== Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp2130.oracle.com with ESMTP id 2nxx2udb0s-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 28 Nov 2018 23:46:16 +0000 Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id wASNkADQ018219 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 28 Nov 2018 23:46:11 GMT Original-Received: from abhmp0020.oracle.com (abhmp0020.oracle.com [141.146.116.26]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id wASNkAdo004409; Wed, 28 Nov 2018 23:46:10 GMT In-Reply-To: <54ba7381c515b5019d5a0322ece9b35a@webmail.orcon.net.nz> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4771.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9091 signatures=668686 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-1810050000 definitions=main-1811280204 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:152871 Archived-At: > I think the docstring is clear, provided that you read all of it; but > it could undoubtedly be improved, especially as this is a slightly > fiddly command to get to grips with. I don't think so. > Perhaps your concern could be addressed by tweaking the paragraph > starting "REGEXP must contain at least one parenthesized subexpression" > so that it says: >=20 > "Non-interactively, REGEXP must contain at least one parenthesized...." >=20 > (which strictly speaking is perhaps less correct than what it says now, > yet I think in practice would make things slightly clearer.) That's in fact worse, as you say. The argument to the function is REGEXP. Just what REGEXP needs to be must be specified accurately. And what REGEXP needs to be has nothing to do with whether the function is invoked interactively. However, in addition to REGEXP needing to be specified precisely, we need to tell users what they need to input, to provide arg REGEXP to the function. Those are two different descriptions. Usually we describe a command first in terms of interactive use. In this case, that means in terms of describing what you need to input. Call it a pattern or whatever, or don't call it anything, but in any case don't call it REGEXP (the arg name) - what you input is not arg REGEXP. We can then say that from your input is constructed arg REGEXP, which is what is matched against... And there we can specify both REGEXP and how it is constructed from your input. The main problem is conflating arg REGEXP with the user input, which is a suffix of REGEXP.