From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Phil Sainty Newsgroups: gmane.emacs.bugs Subject: bug#33541: 26; Doc string of `align-regexp' Date: Thu, 29 Nov 2018 12:22:18 +1300 Message-ID: <54ba7381c515b5019d5a0322ece9b35a@webmail.orcon.net.nz> References: <8aa04dea-d34b-4d58-9671-07e6e575c54d@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1543447291 5133 195.159.176.226 (28 Nov 2018 23:21:31 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 28 Nov 2018 23:21:31 +0000 (UTC) User-Agent: Orcon Webmail Cc: 33541@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Nov 29 00:21:27 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 1gS994-0001Dr-N2 for geb-bug-gnu-emacs@m.gmane.org; Thu, 29 Nov 2018 00:21:26 +0100 Original-Received: from localhost ([::1]:50351 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gS9BB-0001nV-5M for geb-bug-gnu-emacs@m.gmane.org; Wed, 28 Nov 2018 18:23:37 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57749) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gS9Ag-0001fy-Bh for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:23:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gS9Ac-0004eF-BB for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:23:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:49623) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gS9Ac-0004db-4t for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:23:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gS9Ab-0003Fi-S7 for bug-gnu-emacs@gnu.org; Wed, 28 Nov 2018 18:23:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Phil Sainty Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 28 Nov 2018 23:23: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.154344734212441 (code B ref 33541); Wed, 28 Nov 2018 23:23:01 +0000 Original-Received: (at 33541) by debbugs.gnu.org; 28 Nov 2018 23:22:22 +0000 Original-Received: from localhost ([127.0.0.1]:53881 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gS99y-0003Ea-66 for submit@debbugs.gnu.org; Wed, 28 Nov 2018 18:22:22 -0500 Original-Received: from smtp-1.orcon.net.nz ([60.234.4.34]:43554) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gS99w-0003ES-Fb for 33541@debbugs.gnu.org; Wed, 28 Nov 2018 18:22:20 -0500 Original-Received: from [10.253.37.70] (port=41874 helo=webmail.orcon.net.nz) by smtp-1.orcon.net.nz with esmtpa (Exim 4.86_2) (envelope-from ) id 1gS99u-0007OC-5o; Thu, 29 Nov 2018 12:22:18 +1300 Original-Received: from wlgwil-nat-office.catalyst.net.nz ([202.78.240.7]) via [10.253.37.253] by webmail.orcon.net.nz with HTTP (HTTP/1.1 POST); Thu, 29 Nov 2018 12:22:18 +1300 In-Reply-To: <8aa04dea-d34b-4d58-9671-07e6e575c54d@default> X-Sender: psainty@orcon.net.nz X-GeoIP: -- X-Spam_score: -2.9 X-Spam_score_int: -28 X-Spam_bar: -- 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:152870 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. Perhaps your concern could be addressed by tweaking the paragraph starting "REGEXP must contain at least one parenthesized subexpression" so that it says: "Non-interactively, REGEXP must contain at least one parenthesized...." (which strictly speaking is perhaps less correct than what it says now, yet I think in practice would make things slightly clearer.) I would also change "automatically added" to "automatically prefixed". -Phil On 2018-11-29 06:26, Drew Adams wrote: > These two paragraphs seem to contradict each other: > > There is no predefined rule to handle this, but you could easily do it > using a REGEXP like "(". Interactively, all you would have to do is > to mark the region, call 'align-regexp' and enter that regular > expression. > > REGEXP must contain at least one parenthesized subexpression, > typically > whitespace of the form "\\(\\s-*\\)". In normal interactive use, > this is automatically added to the start of your regular expression > after > you enter it. You only need to supply the characters to be lined up, > and > any preceding whitespace is replaced. > > It cannot be the case that both (1) all you have to input as regexp is > "(" and (2) the input regexp must contain a group subexpression. > > It's also unclear to say that REGEXP must contain... and also say that > something gets added automatically to it. > > Yes, it's correct, provided a user interprets "REGEXP" only as the Lisp > argument and not directly as the regexp she enters. Clearer wording > would be welcome, distinguishing (1) what you have to input (do you > need > to include a group subexpression? even if it is the whitespace prefix > "\\(\\s-*\\)"?) from what is required as the REGEXP argument to the > function. > > In particular (minimum fix), it is incorrect to say 'you could easily > do > it using a REGEXP like "("'. There, REGEXP clearly must be the Lisp > argument, not what you type interactively. REGEXP presumably always > requires a group subexpression.