From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: use and doc of function symbol properties [was: bug#11381: 23.3; isearch-search-and-update issue?] Date: Tue, 29 May 2012 17:10:33 -0700 Message-ID: References: <4F9DC154.2000605@groveronline.com> <87ipgggtmw.fsf@mail.jurta.org> <878vhcc4nl.fsf@mail.jurta.org> <87vcjxdt5p.fsf@mail.jurta.org> <87vcjvwtxa.fsf@mail.jurta.org> <87r4ufhfmi.fsf@mail.jurta.org> <878vge3ri7.fsf@mail.jurta.org> <83pq9o1f9s.fsf@gnu.org> <09237F12532B42C381CDBC71FA09EA08@us.oracle.com> <83ehq419bn.fsf@gnu.org> <83d35o11fk.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1338336676 9809 80.91.229.3 (30 May 2012 00:11:16 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 30 May 2012 00:11:16 +0000 (UTC) Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: "'Eli Zaretskii'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed May 30 02:11:14 2012 Return-path: Envelope-to: ged-emacs-devel@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 1SZWVO-0007T7-Bq for ged-emacs-devel@m.gmane.org; Wed, 30 May 2012 02:11:14 +0200 Original-Received: from localhost ([::1]:43249 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZWVN-0002Uu-Qu for ged-emacs-devel@m.gmane.org; Tue, 29 May 2012 20:11:13 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:60160) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZWVF-0002Ua-D3 for emacs-devel@gnu.org; Tue, 29 May 2012 20:11:11 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SZWVD-0000aa-68 for emacs-devel@gnu.org; Tue, 29 May 2012 20:11:04 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]:18658) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZWV6-0000YQ-AN; Tue, 29 May 2012 20:10:56 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q4U0AqZh018979 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 30 May 2012 00:10:53 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q4U0AqbW020991 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 30 May 2012 00:10:52 GMT Original-Received: from abhmt110.oracle.com (abhmt110.oracle.com [141.146.116.62]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id q4U0Apws024144; Tue, 29 May 2012 19:10:51 -0500 Original-Received: from dradamslap1 (/10.159.177.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 29 May 2012 17:10:51 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <83d35o11fk.fsf@gnu.org> Thread-Index: Ac09EpOuGve2n0CgQ5qu/EcCKMtZzgA3HF4g X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1) X-Received-From: 141.146.126.227 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:150684 Archived-At: > > Even so, I think that `yank' and `kill' are pretty clear even > > without reading their descriptions. > > Not to me. "For commands that do a yank" is not a description, it's > tautology at best. "Ensures that the region about to be deleted is > not yanked"? why would it be yanked otherwise? and why the value is > 'yank' if it "ensures the region will NOT be yanked"? That just > doesn't make any sense! It does makes sense, I think, but perhaps only after you understand what it does, not necessarily as a lesson. ;-) Let me try to do a little better. Whenever the value of property `delete-selection' for a command symbol is non-nil, and you are in `delete-selection-mode', the text of the active region is removed. Always. That is the first thing to understand. This removal happens before - or instead of - the action normally performed by the command. That is the second thing to understand. So in the above text, "the region about to be deleted" refers to the deletion of the active region, which takes place before the yank command does its own thing (yanks). And "ensures the region will NOT be yanked" means that the property value `yank' ensures that when the yank command does its yanking it does not just yank the exact same text that was just deleted - the active region text - even if that was the text that the kill ring offered. That's an attempt to explain the existing commentary text. Some more help below. > 'kill'? let's see... "`kill-region' is used on the selection, rather > than `delete-region'". So? why would that matter, and when would I > want the former rather than the latter? You would use `kill' when you want the active region text killed instead of being simply deleted. That's all that that is trying to say. > And what is "Text selected with the mouse is typically > yankable anyway" about? why "anyway"? No idea, sorry. > > I'm not saying the existing descriptions should not be > > changed. I'm asking you what changes you have in mind. > > How can I explain what I don't understand? I _really_ have no clear > idea about what each value does, can you believe that? If I'd study > the code long enough, I'd eventually understand, but I didn't. I see. I thought you were saying before that you understood the code, and that it is necessary to study the code in order to understand. I misunderstood probably from your saying this: the only place you can really understand what these properties mean is by looking at the code in delsel.el that handles them, because even the commentary in delsel.el leaves a lot of place for improvement. I took that to mean that you "really understand" the code, and that the commentary description does not live up to such an understanding. My bad. > > > What is needed is a clear description what each value does, > > For instance? What is missing, in your opinion? > > I don't know. How about if you try explaining each value in full, > from scratch? Assume that only primitives like kill-region, > delete-region, 'yank', etc. are known, all the rest is not. Explain > the effect of each value, both on the text that was selected and on > any other text that's involved. Give at least one example for a use > case where each value will be useful. That kind of stuff. See if this helps at all - In all cases when `delete-selection-mode' is turned on and the `delete-selection' value of a command symbol is non-nil, the text of the active region is removed. It is either deleted or killed (i.e., deleted and moved to the `kill-ring'). It is killed only if the value of property `delete-selection' is `kill'. The action of the invoked command itself is either carried out (after deletion of the active region), which is the case for `delete-selection' values `yank' and `t', or not (it is ignored), which is the case for values `supersede' and `kill'. `delete-selection' value `yank' ensures that the invoked yanking command does not yank the same text as that in the region. The kill ring is rotated if necessary, so that the yank operation is not a no-op. Here is a summary of the `delete-selection' property values. You can apply a value to a command symbol to make the command delete the active region text and perhaps do something more: `kill' - Use it if you want the command to kill the region text, so you can yank it later. The command's own operation does NOT take place - it is superseded by the region killing. Typically, the command itself is a kill command: its own killing is replaced by killing the active region. `supersede' - Use it for a command that deletes text that you do not want to yank later. The command's own operation does NOT take place - it is superseded by the region deletion. Typically, the command is a deletion command: its own deletion is replaced by deleting the active region. `t' - Use it for a command that inserts text. The command's insertion operation takes place after deleting the active region. `yank' - Use it for a command that yanks text. The command's yank operation takes place after deleting the active region. If the kill-ring entry to be yanked has the same text as the region, then first rotate the kill ring so that the yank will not be a no-op. `nil' - Invoke the command normally. Delete-selection mode does nothing for a command whose `delete-selection' property value is nil. That is a summary, but it also outlines the important use cases. In fact, there is nothing that requires you to use only a deletion command with `supersede' or only an insertion command with `t', etc. Example use cases: * If the command action is to kill some text, then you might want it to kill the region instead, when it is active. In this case, use `kill' as the `delete-selection' value. * If the command action is to delete some text without killing it, then you might want it to delete the active region instead (without killing it). In this case, use `supersede' as the `delete-selection' value. * If the command action is to insert some text, you typically want that text to replace the active region. In this case, use `t' as the `delete-selection' value. * If the command action is to yank some text, then use `yank' as the `delete-selection' value. Concrete examples from Org mode: `org-self-insert-command' gets value `t' (i.e., replace) `org-delete-char' gets value `supersede' (i.e., just delete) `org-yank' gets `value yank' (i.e., replace, but prevent a no-op) FWIW, Org mode does EXACTLY the same thing for handling `flyspell-mode': It puts property `flyspell-delayed' on commands `org-self-insert-command' and `org-delete-char'. And it does EXACTLY the same thing for handling `pabbrev-mode': It puts property `pabbrev-expand-after-command' on command `org-self-insert-command'. The attachment of properties to function symbols in order to affect behavior in some mode is not a new idiom. And it is not limited to Emacs Lisp. In any case, this is all apparently moot, since Stefan appears to want to do away with this (simple & elegant) mechanism and instead do something like what was done recently for shift-select or even his completion tables. http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11381#62 If you had trouble understanding the delsel approach and code, well, then ... bonjour les degats when it is replaced by a concoction a la completion tables. ;-) And good luck with the relevant doc strings and Commentary. HTH.