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: use and doc of function symbol properties [was: bug#11381: 23.3; isearch-search-and-update issue?] Date: Mon, 28 May 2012 10:34:34 -0700 Message-ID: <09237F12532B42C381CDBC71FA09EA08@us.oracle.com> 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> 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 1338226520 17326 80.91.229.3 (28 May 2012 17:35:20 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 28 May 2012 17:35:20 +0000 (UTC) Cc: 11381@debbugs.gnu.org, emacs-devel@gnu.org To: "'Eli Zaretskii'" , "'Stefan Monnier'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon May 28 19:35:17 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 1SZ3qb-0004A2-Mw for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 19:35:13 +0200 Original-Received: from localhost ([::1]:38494 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ3qb-0003hz-Cj for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 13:35:13 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:34693) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ3qX-0003hS-1Q for emacs-devel@gnu.org; Mon, 28 May 2012 13:35:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SZ3qU-00089r-Vh for emacs-devel@gnu.org; Mon, 28 May 2012 13:35:08 -0400 Original-Received: from rcsinet15.oracle.com ([148.87.113.117]:39318) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ3qQ-0007y7-OL; Mon, 28 May 2012 13:35:02 -0400 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by rcsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q4SHYo4K004919 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 28 May 2012 17:34:51 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q4SHYnwI020544 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 28 May 2012 17:34:49 GMT Original-Received: from abhmt104.oracle.com (abhmt104.oracle.com [141.146.116.56]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id q4SHYm11001927; Mon, 28 May 2012 12:34:49 -0500 Original-Received: from dradamslap1 (/10.159.220.56) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 28 May 2012 10:34:48 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <83pq9o1f9s.fsf@gnu.org> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 Thread-Index: Ac086T4RcmhF2wJTT4a4bSGUphp2gAAAMUiw X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1) X-Received-From: 148.87.113.117 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:150669 Archived-At: The question you (Eli) raise is not specific to isearch or to delsel. The proper place to discuss it is emacs-devel - especially if you propose to change things. So I'm ccing emacs-devel - but bug #11381 should be dropped from the cc list from now on. > Actually, I very much dislike this "feature" of putting properties on > function symbols, or at least the way we use it. The problem is > documentation: We agree that that is the problem. It is not something else. > there's no good place visible to users where to > document the possible values of these properties and their meanings, > so they are only documented in the code. Yes. Documentation could be improved. But the use of symbol properties, including for function symbols, is nothing special. It is similar to using attributes or methods with objects in OOP. What's sometimes missing perhaps is better documentation/discoverability. Emacs Lisp symbols are rudimentary objects, and, yes, there is not a lot of built-in support for discovering or navigating them - how particular properties are used in various contexts etc. > This makes maintenance much harder and error-prone than > it needs to be. If Emacs maintainers substitute basic Emacs keys/commands here and there then they need to be aware of `delete-selection-mode' - yes. The same is true for other modes that users might use - whether visual lines or whatever. Changing one thing can affect another. The consequence for delsel if that advice is ignored is to risk making it a no-op in some cases: you can neuter `delete-selection-mode' if you do not pay attention when you replace commands with new ones (e.g. in some mode). Wrt the user, and visibility of this information: In some cases, the user (yes, user) is an Elisp programmer, and s?he would sometimes need to consult the code anyway, depending on what s?he wants to do. A user of delsel can be someone who never changes such a property on any function symbol (most users), or it can be someone who does. For the latter, it would probably not be necessary to consult the delsel code if the documentation included some information that is currently only in the delsel.el Commentary. [This is not unique to delsel.el, BTW - there are other libraries for which a programming user must consult the Commentary in order to understand - even when it might not be necessary to read the code itself. IOW, there are other cases where some of the Commentary info might fruitfully be added to the doc. Library thingatpt.el comes to mind - e.g., the doc strings where we say "See the file `thingatpt.el' for documentation on how to define a symbol as a valid THING." That's almost as long as the info in the Commentary.] Typically, someone minimally familiar with using delsel as a programmer can easily answer a question from a user about what's happening or how to change the behavior. This info could be added to the `delete-selection-mode' doc string. The doc could include info about programming/customizing the behavior. That info is not a big deal IMO, either to present or to understand. Some libraries have whole Info manuals that delve into such programming/customization aspects. Library delsel.el is very simple, so that info could just be added to the doc string for the mode. The entire Commentary text that explains it is only a few lines long (labeled "Interface"), and that is all that is needed, I think. > Look at delsel.el, for one such example. The various uses of the > related properties, scattered through half a dozen other Lisp > packages, are completely obfuscated, and 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. Not sure I agree, though it is hard to disagree that the application of properties to function symbols is scattered. It is of course the case that the place to look for understanding delete-selection mode is function `delete-selection-mode'. And it is true that today that means looking also at the delsel.el Commentary. Moving that info to the doc string would help. Can you be more specific about what is missing from the Commentary in delsel.el? It seems to me that how delsel works and how to customize the behavior is pretty well explained there, if a bit succinctly. What else would you like to see documented in this regard? > I say, either we start documenting these properties in the doc strings > and in the manual, or we should deprecate and discourage the practice > of using them. OK for the former. I disagree with the latter. Let's not throw out the baby with the bathwater. I really don't think this is a big deal. I've seen a few user questions about delsel behavior in help-gnu-emacs over the years, and IIRC all of them had an obvious explanation to someone familiar with the behavior of delsel (which is quite simple). Putting the info about that behavior into the doc string would be helpful - and sufficient, I think. But of course that won't stop a few "end" users from having the occasional question because some library they picked up effectively customizes delsel behavior without saying so. A typical question comes from someone who already uses delsel (and who is used to using it), who then picks up a library that changes some key bindings, effectively replacing some commands that are handled by delsel with some commands that are not. This case is not a big deal. Such a user can tell right away that something has changed the delsel behavior, and a quick question to help-gnu-emacs - or a quick check of the new doc string - would likely turn on the light. But a user who has never used delsel before, and who already uses some library that substitutes keys/commands so that delsel becomes a no-op for them, will perhaps not understand why delsel does not seem to behave as advertised. IOW, trying to understand the expected vanilla behavior of delsel (having never used it), and trying to understand a modified behavior at the same time, might be more difficult. But even that user, if s?he consults the new doc string, would have a good chance of understanding the situation. Attaching properties to Lisp function symbols in order to affect behavior is as old as Lisp symbols themselves. Please do not try to discourage this practice. But it is fine to try to improve the documentation or discoverability. [Belongs in a separate thread, at another time, but if `delete-selection-mode' were the default (yes) then: (a) users new to Emacs would find behavior much closer to what they are used to, and (b) Emacs developers (including 3rd-party) would be more conscious of delsel, so would likely DTRT wrt it more often.] (Just one opinion.)