From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad Date: Fri, 21 Aug 2015 10:17:56 -0700 (PDT) Message-ID: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1440177565 27992 80.91.229.3 (21 Aug 2015 17:19:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 21 Aug 2015 17:19:25 +0000 (UTC) To: 21315@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Aug 21 19:19:11 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1ZSpyB-00050g-8D for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Aug 2015 19:19:11 +0200 Original-Received: from localhost ([::1]:42946 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSpyA-0007cf-6h for geb-bug-gnu-emacs@m.gmane.org; Fri, 21 Aug 2015 13:19:10 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48055) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSpy5-0007cK-PN for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 13:19:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZSpy3-00054X-0Q for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 13:19:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:42527) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSpy2-00054S-Si for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 13:19:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1ZSpy2-0005Hn-LK for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 13:19:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 21 Aug 2015 17:19:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 21315 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.144017748720219 (code B ref -1); Fri, 21 Aug 2015 17:19:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 21 Aug 2015 17:18:07 +0000 Original-Received: from localhost ([127.0.0.1]:34721 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZSpx8-0005G3-W1 for submit@debbugs.gnu.org; Fri, 21 Aug 2015 13:18:07 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:37821) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZSpx6-0005Fu-5W for submit@debbugs.gnu.org; Fri, 21 Aug 2015 13:18:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZSpx5-0004mf-3h for submit@debbugs.gnu.org; Fri, 21 Aug 2015 13:18:03 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:49797) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSpx5-0004mZ-1h for submit@debbugs.gnu.org; Fri, 21 Aug 2015 13:18:03 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47815) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSpx4-0007EU-3n for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 13:18:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZSpx1-0004lv-Ds for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 13:18:02 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:25083) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZSpx1-0004lo-6y for bug-gnu-emacs@gnu.org; Fri, 21 Aug 2015 13:17:59 -0400 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 t7LHHw10026684 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Fri, 21 Aug 2015 17:17:58 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0022.oracle.com (8.13.8/8.13.8) with ESMTP id t7LHHvpe023858 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL) for ; Fri, 21 Aug 2015 17:17:58 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id t7LHHvpH022280 for ; Fri, 21 Aug 2015 17:17:57 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x 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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:105677 Archived-At: In Emacs 24.4 you changed not only the signature of these commands but also their interactive behavior, by adding optional arg REGION and giving users control over it with the prefix arg. Unfortunately, the doc for this new behavior is horribly inadequate. 1. The Emacs manual says nothing about the new behavior. It should cover it. 2. The doc strings are awful in this regard. They say only "The optional argument REGION if non-nil, indicates that we're not just copying some text between BEG and END, but we're copying the region." That's worse than saying nothing - a complete cop-out. If the doc is going to say something like "we're copying the region" and if that phrase is expected to mean anything then the doc needs to say what it means by that. Describe the user-observable behavior difference between using a prefix arg and not using it. Currently, the use of a prefix arg is not even mentioned. As bad as the description of parameter REGION is, it is not even connected with the use of a prefix arg. 3. The command is not documented at all in the Elisp manual. It need not be, but the current state is that a user has no real information about this at all, and that is not good. 4. I find nothing in NEW for Emacs 24.4 (when this was released) about this. User-observable behavior changes like this should be documented there. Developers should not be allowed to commit program changes like this without updating the doc appropriately. Yes, leader resources are scarce, and people are overworked. But it's too bad, as it fosters bad habits, unless the person who committed the code change happens to be the one who fixes this doc bug, and can thus learn from the mistake. In GNU Emacs 25.0.50.1 (i686-pc-mingw32) of 2015-07-31 on LEG570 Bzr revision: 8d332aeccab2208e6c6bd434738565e6abf12043 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --host=3Di686-pc-mingw32 --enable-checking=3Dyes,glyphs'