From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#33541: 26; Doc string of `align-regexp' Date: Thu, 29 Nov 2018 09:25:49 +0200 Message-ID: <83a7lse45e.fsf@gnu.org> References: <8aa04dea-d34b-4d58-9671-07e6e575c54d@default> <54ba7381c515b5019d5a0322ece9b35a@webmail.orcon.net.nz> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1543476332 5633 195.159.176.226 (29 Nov 2018 07:25:32 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 29 Nov 2018 07:25:32 +0000 (UTC) Cc: psainty@orcon.net.nz, 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 08:25: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 1gSGhS-0001LY-V8 for geb-bug-gnu-emacs@m.gmane.org; Thu, 29 Nov 2018 08:25:27 +0100 Original-Received: from localhost ([::1]:52613 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gSGjX-0003pI-3T for geb-bug-gnu-emacs@m.gmane.org; Thu, 29 Nov 2018 02:27:37 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53701) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gSGjH-0003mk-AG for bug-gnu-emacs@gnu.org; Thu, 29 Nov 2018 02:27:24 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gSGi2-0008Vs-Qb for bug-gnu-emacs@gnu.org; Thu, 29 Nov 2018 02:26:03 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:49774) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gSGi2-0008Vk-Mh for bug-gnu-emacs@gnu.org; Thu, 29 Nov 2018 02:26:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gSGi2-0006Tc-GM for bug-gnu-emacs@gnu.org; Thu, 29 Nov 2018 02:26:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 29 Nov 2018 07:26:02 +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.154347635324881 (code B ref 33541); Thu, 29 Nov 2018 07:26:02 +0000 Original-Received: (at 33541) by debbugs.gnu.org; 29 Nov 2018 07:25:53 +0000 Original-Received: from localhost ([127.0.0.1]:54032 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gSGht-0006TF-1m for submit@debbugs.gnu.org; Thu, 29 Nov 2018 02:25:53 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:43415) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gSGhr-0006T3-Ga for 33541@debbugs.gnu.org; Thu, 29 Nov 2018 02:25:51 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gSGhh-0008BD-El for 33541@debbugs.gnu.org; Thu, 29 Nov 2018 02:25:46 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:44154) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gSGhc-00087K-UQ; Thu, 29 Nov 2018 02:25:37 -0500 Original-Received: from [176.228.60.248] (port=2767 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gSGhc-0002b1-6Z; Thu, 29 Nov 2018 02:25:36 -0500 In-reply-to: (message from Drew Adams on Wed, 28 Nov 2018 15:46:09 -0800 (PST)) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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:152877 Archived-At: > Date: Wed, 28 Nov 2018 15:46:09 -0800 (PST) > From: Drew Adams > Cc: 33541@debbugs.gnu.org > > 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. I don't see how this doc string could be improved by just discussing it. Someone who understands well enough what the feature does should sit down and prepare more clear and coherent text, and then submit a patch. FWIW, I tried and didn't succeed too well. (Which should not discourage others from trying, of course.) TIA