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#22296: 25.1.50; Document changes to `delete-selection-mode' Date: Sun, 3 Jan 2016 11:54:12 -0800 (PST) Message-ID: <02f413b1-6aa6-4095-a9a9-a60c50faa5ca@default> References: <<<<<660d1a46-fd5a-460f-8f26-50ba9a52cc60@default>>>>> <<<<<83mvsmadhv.fsf@gnu.org>>>>> <<<<940d59ef-c3d6-42df-ba0c-602cc154d431@default>>>> <<<<834meua953.fsf@gnu.org>>>> <<<68435980-44a2-4d33-8f64-8fbbdedb4a4e@default>>> <<<83vb7a8pxi.fsf@gnu.org>>> <<8b4cae3f-6f4c-4784-85fc-36a659fe15fd@default>> <<83r3hy8owz.fsf@gnu.org>> 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 1451850925 11273 80.91.229.3 (3 Jan 2016 19:55:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 3 Jan 2016 19:55:25 +0000 (UTC) Cc: 22296@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jan 03 20:55:11 2016 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 1aFokA-0002qD-KU for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Jan 2016 20:55:10 +0100 Original-Received: from localhost ([::1]:42747 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aFok9-0004gF-P4 for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Jan 2016 14:55:09 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52249) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aFok5-0004g3-Vf for bug-gnu-emacs@gnu.org; Sun, 03 Jan 2016 14:55:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aFok2-0007oS-OT for bug-gnu-emacs@gnu.org; Sun, 03 Jan 2016 14:55:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:48689) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aFok2-0007oO-LE for bug-gnu-emacs@gnu.org; Sun, 03 Jan 2016 14:55:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aFok2-0004RA-Fi for bug-gnu-emacs@gnu.org; Sun, 03 Jan 2016 14:55: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: Sun, 03 Jan 2016 19:55:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 22296 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 22296-submit@debbugs.gnu.org id=B22296.145185086217004 (code B ref 22296); Sun, 03 Jan 2016 19:55:02 +0000 Original-Received: (at 22296) by debbugs.gnu.org; 3 Jan 2016 19:54:22 +0000 Original-Received: from localhost ([127.0.0.1]:36909 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aFojO-0004QC-JD for submit@debbugs.gnu.org; Sun, 03 Jan 2016 14:54:22 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:23080) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aFojN-0004Px-J3 for 22296@debbugs.gnu.org; Sun, 03 Jan 2016 14:54:22 -0500 Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u03JsEwm004352 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sun, 3 Jan 2016 19:54:14 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0021.oracle.com (8.13.8/8.13.8) with ESMTP id u03JsDbC018839 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sun, 3 Jan 2016 19:54:14 GMT Original-Received: from abhmp0010.oracle.com (abhmp0010.oracle.com [141.146.116.16]) by userv0121.oracle.com (8.13.8/8.13.8) with ESMTP id u03JsDdM024394; Sun, 3 Jan 2016 19:54:13 GMT In-Reply-To: <<83r3hy8owz.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:111164 Archived-At: > > > > How is a user supposed to understand how to use d-s-mode if these > > > > things are not documented - either in a doc string or in a manual? > > > > > > How did they understand this before? > > > > It was in the doc string of d-s-mode. Each of the possible > > property values was described. >=20 > In what version of Emacs? I tried 24.3 and 24.1, and didn't see that > there. Maybe I'm blind or didn't look where you intended me to look. > But then you never actually said that, did you? My bad. I thought this was in the d-s-mode doc string. Sorry for making you look for it to no avail. I should have checked first. Prior to the existence of `delete-selection-helper' (e.g., Emacs 23) this info was only in the Commentary. In Emacs 24 and later it is also in the doc string of `delete-selection-helper'. That helper-function doc string is really not the right place for it, IMO (though I am glad it was at least added to some doc string). Users will look to the command/mode doc string more than to a helper-function doc string, for information about how to use delete-selection mode. (And as I said, the Commentary and the `delete-selection-helper' doc string are now out of sync wrt `kill'.) So let me be clear that I do not think the doc is adequate. Specifically: it should tell you how to set the d-s-mode behavior for a given command. And in doing that, it should list the possible values for symbol property `delete-selection'. Where this information is provided to users is another question. At a minimum, I think it belongs in the `delete-selection-mode' doc string. And I would like to see d-s mode documented better in the Emacs manual. Currently, this is all that we say about it there (node `Using Region'): If you enable Delete Selection mode, a minor mode, then inserting text while the mark is active causes the text in the region to be deleted first. To toggle Delete Selection mode on or off, type `M-x delete-selection-mode'. The last sentence is a bit redundant, both wrt toggling and on/off and wrt Delete Selection mode and `delete-selection-mode'. It's good to say, but if you are really interested in saving words then please consider more information and less verbiage here. D-s mode is not only about replacing selected text by text you type. It also deletes selected text when you hit certain deletion keys. This info is missing. But the main thing missing, IMO, is how to specify the behavior for a given command, and what the possible behaviors are for a given command. This is particularly important for someone writing a mode that binds keys to new commands that delete text. The mode writer will need to teach the mode to be handled well by d-s-mode, and for that s?he will need to know about symbol property `delete-selection. Whether most Emacs users need to know this or it could be presented only in the Elisp manual is another question. I think that an end user will also want to know that s?he can override the default d-s-mode behavior for any given commands, and that the way to do that is to set property `delete-selection' on the command symbol. Pretty simple to do, but you need to know about it to do it. That d-s mode has never been adequately documented is not a reason not to document it properly, IMO. Yes, I and others no doubt learned how to use it by reading the source code. But that should not be the main or the only way that users have to learn about it. Just one opinion.