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: Mon, 28 May 2012 11:26:35 -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> 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 1338229631 9461 80.91.229.3 (28 May 2012 18:27:11 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 28 May 2012 18:27:11 +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 Mon May 28 20:27:08 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 1SZ4em-0007Is-Gz for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 20:27:04 +0200 Original-Received: from localhost ([::1]:49234 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ4em-0003eU-7d for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 14:27:04 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:59083) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ4ei-0003e9-UU for emacs-devel@gnu.org; Mon, 28 May 2012 14:27:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SZ4eh-0003Zd-4Z for emacs-devel@gnu.org; Mon, 28 May 2012 14:27:00 -0400 Original-Received: from rcsinet15.oracle.com ([148.87.113.117]:33915) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ4ec-0003YS-Ob; Mon, 28 May 2012 14:26:54 -0400 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by rcsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q4SIQocS004903 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 28 May 2012 18:26:51 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q4SIQnsA003372 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 28 May 2012 18:26:50 GMT Original-Received: from abhmt116.oracle.com (abhmt116.oracle.com [141.146.116.68]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id q4SIQnhr024442; Mon, 28 May 2012 13:26:49 -0500 Original-Received: from dradamslap1 (/10.159.220.56) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 28 May 2012 11:26:49 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac08+sGHu9tP0VUeSUi+3SU9orFsZAAAZRpQ In-Reply-To: <83ehq419bn.fsf@gnu.org> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] 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:150671 Archived-At: > > Can you be more specific about what is missing from the > > Commentary in delsel.el? > > It basically doesn't explain anything apart of the fact that the > property can have several values. The exact effect of each value is > left unclear to the degree of obfuscation. The effect of each value is described, though perhaps imperfectly and not to your liking. Again, what specifically do you feel is missing? Just repeating "obfuscation" does not help. Please specify the information that you would add. > And the names of the values are similarly non-specific. The names do not stand alone without their descriptions. Even so, I think that `yank' and `kill' are pretty clear even without reading their descriptions. `supersede' is not so obvious, but its description seems clear. "non-nil" should be "anything else non-nil". And we should say that this is the usual case. FWIW, in my version of delsel.el I changed the wording a tiny bit, to improve it slightly: ;; The property can have one of these values: ;; ;; `yank' - For commands that do a yank. Ensures that the region ;; about to be deleted is not yanked. ;; ;; `supersede' - Delete the active region and ignore the current ;; command: the command just deletes the region. ;; ;; `kill' - `kill-region' is used on the selection, rather than ;; `delete-region'. Text selected with the mouse is ;; typically yankable anyway. ;; ;; anything else non-nil - Deletes the active region prior to ;; executing the command, which inserts replacement ;; text. This is the usual case. I'm not saying the existing descriptions should not be changed. I'm asking you what changes you have in mind. > What is needed is a clear description what each value does, For instance? What is missing, in your opinion? > and it should be part of the doc string. Right now, this info is only > available by reading the code. Agreed.