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 08:43:05 -0800 (PST) Message-ID: <86584c33-6e52-4cf5-8e22-bb9952b296b2@default> References: <> <<83h8tk9chp.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 1511541856 18070 195.159.176.226 (24 Nov 2017 16:44:16 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 24 Nov 2017 16:44:16 +0000 (UTC) Cc: 29373-done@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 17:44:08 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 1eIH5A-0003v4-Nv for geb-bug-gnu-emacs@m.gmane.org; Fri, 24 Nov 2017 17:44:04 +0100 Original-Received: from localhost ([::1]:50146 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eIH5I-0001T8-3n for geb-bug-gnu-emacs@m.gmane.org; Fri, 24 Nov 2017 11:44:12 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45572) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eIH5B-0001OR-S2 for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 11:44:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eIH58-0003Au-HU for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 11:44:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:47489) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eIH58-000386-EI for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 11:44:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eIH58-0003jf-1x for bug-gnu-emacs@gnu.org; Fri, 24 Nov 2017 11:44: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: Fri, 24 Nov 2017 16:44:02 +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-done@debbugs.gnu.org id=D29373.151154179814296 (code D ref 29373); Fri, 24 Nov 2017 16:44:02 +0000 Original-Received: (at 29373-done) by debbugs.gnu.org; 24 Nov 2017 16:43:18 +0000 Original-Received: from localhost ([127.0.0.1]:56170 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eIH4Q-0003iW-8G for submit@debbugs.gnu.org; Fri, 24 Nov 2017 11:43:18 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:30766) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eIH4O-0003iC-Jl for 29373-done@debbugs.gnu.org; Fri, 24 Nov 2017 11:43:17 -0500 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id vAOGh8qf026787 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 24 Nov 2017 16:43:09 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id vAOGh7E8011006 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 24 Nov 2017 16:43:08 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 vAOGh6ur028550; Fri, 24 Nov 2017 16:43:07 GMT In-Reply-To: <<83h8tk9chp.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: userv0022.oracle.com [156.151.31.74] 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:140316 Archived-At: > -----Original Message----- > From: Eli Zaretskii [mailto:eliz@gnu.org] > Sent: Friday, November 24, 2017 2:51 AM > To: Drew Adams > Cc: 29373-done@debbugs.gnu.org > Subject: Re: bug#29373: 24.5; doc string of `self-insert-uses-region- > functions' >=20 > > Date: Mon, 20 Nov 2017 18:56:15 -0800 (PST) > > From: Drew Adams > > > > Two lines of the doc string are too long. >=20 > Longer than 79 characters? I didn't find any such lines. Where do you see 79 as the recommended max length? Traditionaly it has been 70, IIRC. >From (elisp) `Documentation Tips': Format the documentation string so that it fits in an Emacs window on an 80-column screen. It is a good idea for most lines to be no wider than 60 characters. The first line should not be wider than 67 characters or it will look bad in the output of 'apropos'. https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tip= s.html 1 out of the 5 lines is less than 61 chars - not most. But if you're happy with the lengths as is, fine. > > The doc string is close to incomprehensible. >=20 > Such derogatory remarks are best kept out of bug reports. The facts > are grave enough to tell we should fix this. Nothing derogatory intended. That's a summary of the problem - lack of clarity overall. For me, at least, the wording of this doc is not very understandable. I have no idea who wrote it, nor do I care. It's not about blaming or attacking anyone. It's about calling your attention to what I, at least, think is a doc string that needs some love (improvement). And the overall problem is not the technical content; it is the lack of clarity - comprehensibility. To me, at least. Anyway, I'm sure you made an improvement, whatever change you made. Thanks for that.