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#29373: 24.5; doc string of `self-insert-uses-region-functions' Date: Fri, 24 Nov 2017 09:33:42 -0800 (PST) Message-ID: References: <<>> <<<83h8tk9chp.fsf@gnu.org>>> <<86584c33-6e52-4cf5-8e22-bb9952b296b2@default>> <<83y3mv8v1r.fsf@gnu.org>> 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 1511544851 8153 195.159.176.226 (24 Nov 2017 17:34:11 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 24 Nov 2017 17:34:11 +0000 (UTC) Cc: 29373@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Nov 24 18:34:06 2017 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 1eIHrY-0001ib-Lv for geb-bug-gnu-emacs@m.gmane.org; Fri, 24 Nov 2017 18:34:04 +0100 Original-Received: from localhost ([::1]:50477 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eIHrf-0001hy-Qd for geb-bug-gnu-emacs@m.gmane.org; Fri, 24 Nov 2017 12:34:11 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34634) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eIHrZ-0001ho-Vl for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 12:34:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eIHrV-0008KS-UH for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 12:34:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:47602) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eIHrV-0008Jq-Qm for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 12:34:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eIHrV-00070u-KS for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 12:34:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 24 Nov 2017 17:34:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 29373 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 29373-submit@debbugs.gnu.org id=B29373.151154483226945 (code B ref 29373); Fri, 24 Nov 2017 17:34:01 +0000 Original-Received: (at 29373) by debbugs.gnu.org; 24 Nov 2017 17:33:52 +0000 Original-Received: from localhost ([127.0.0.1]:56283 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eIHrM-00070X-DX for submit@debbugs.gnu.org; Fri, 24 Nov 2017 12:33:52 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:49802) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eIHrK-00070K-Ea for 29373@debbugs.gnu.org; Fri, 24 Nov 2017 12:33:50 -0500 Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id vAOHXhwN018645 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 24 Nov 2017 17:33:44 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserv0021.oracle.com (8.14.4/8.14.4) with ESMTP id vAOHXhNs030877 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 24 Nov 2017 17:33:43 GMT Original-Received: from abhmp0006.oracle.com (abhmp0006.oracle.com [141.146.116.12]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id vAOHXhSD021038; Fri, 24 Nov 2017 17:33:43 GMT In-Reply-To: <<83y3mv8v1r.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4615.0 (x86)] X-Source-IP: aserv0021.oracle.com [141.146.126.233] 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:140324 Archived-At: > Sometimes it's impossible to limit a line to 70 characters without > incurring worse problems. This is one such case. I don't see any such "worse problems" in this case. Without any change to the wording (which does need to be changed), this shows no "worse problems": Special hook to tell if `self-insert-command' will use the region. It must be called via `run-hook-with-args-until-success' with no arguments. Any `post-self-insert-command' which consumes the region should register a function on this hook so that things like `delete-selection-mode' can refrain from consuming the region. > > > > The doc string is close to incomprehensible. > > > > > > Such derogatory remarks are best kept out of bug reports. > > > The facts are grave enough to tell we should fix this. > > > > Nothing derogatory intended. >=20 > That sentence could simply be omitted without any effect on the > report. May I suggest that you try to refrain from such unneeded > remarks? >=20 > > That's a summary of the problem - lack of clarity overall. >=20 > "Lack of clarity" would be fine (although it, too, adds nothing). > "Incomprehensible" is not a summary. "Incomprehensible" was not the summary I used. "Close to incomprehensible" is the summary I used. I stand by that characterization, as one user reporting a doc problem: to me, the doc string was close to incomprehensible. You might not find it so. It's understandable that a new doc string might not have had the attention it deserves, and so is not as clear as it could be. To me, this one was not really understandable. Perhaps you prefer the statement, "I don't understand this doc string, and I think others may also have trouble making sense of it." And no, I don't think that such a statement adds nothing, even if it is better if accompanied by guesses about the meaning, suggestions for improvement, or pointing out particular places that are especially problematic for the reporter. If a reporter has no clue what is meant and no clue what parts are particularly unclear, the simple report that a doc string is unclear to that reporter can help. We can disagree about this, of course. But my guess is that if you agree with the reporter after reading such an incomplete "Huh?" report then the aim is reached. And if you disagree with the reporter - the doc is clear to you, even if the reporter doesn't understand it at all - it is still good that the perceived problem was reported, and no harm was done. We can disagree about this too, of course.