From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii 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 23:43:43 +0300 Message-ID: <83d35o11fk.fsf@gnu.org> 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> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: dough.gmane.org 1338237835 2396 80.91.229.3 (28 May 2012 20:43:55 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 28 May 2012 20:43:55 +0000 (UTC) Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon May 28 22:43:54 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 1SZ6n9-0003bw-1a for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 22:43:51 +0200 Original-Received: from localhost ([::1]:48882 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ6n8-000822-Df for ged-emacs-devel@m.gmane.org; Mon, 28 May 2012 16:43:50 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:42986) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ6n4-00081h-KL for emacs-devel@gnu.org; Mon, 28 May 2012 16:43:47 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SZ6n2-0007ci-L7 for emacs-devel@gnu.org; Mon, 28 May 2012 16:43:46 -0400 Original-Received: from mtaout22.012.net.il ([80.179.55.172]:49360) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SZ6n2-0007cQ-DC for emacs-devel@gnu.org; Mon, 28 May 2012 16:43:44 -0400 Original-Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0M4R00C002S8SC00@a-mtaout22.012.net.il> for emacs-devel@gnu.org; Mon, 28 May 2012 23:43:40 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.210.75]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0M4R00BUQ2WRTRB0@a-mtaout22.012.net.il>; Mon, 28 May 2012 23:43:40 +0300 (IDT) In-reply-to: X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-Received-From: 80.179.55.172 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:150672 Archived-At: > From: "Drew Adams" > Cc: , > Date: Mon, 28 May 2012 11:26:35 -0700 > > > And the names of the values are similarly non-specific. > > The names do not stand alone without their descriptions. I'm saying that the names don't help to understand the descriptions, that's all. If the descriptions were clear, I would care much less for the names. As things are, I'm grasping at every straw in sight. > 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! '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? And what is "Text selected with the mouse is typically yankable anyway" about? why "anyway"? Etc., etc. These are riddles, or maybe notes for someone who once knew everything about this but forgot. This is not documentation suitable for first-time reading. It leaves too much to previous knowledge. > 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. > > 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.