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: make-variable-buffer-local change Date: Fri, 25 Sep 2009 15:10:20 -0700 Message-ID: <9D911504D7AD429189A20B200265EC58@us.oracle.com> References: <200909251609.n8PG97YN020225@godzilla.ics.uci.edu><6A896C20C65941FE96D239B7E5A1C667@us.oracle.com><83fxaau9hd.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1253916657 20154 80.91.229.12 (25 Sep 2009 22:10:57 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 25 Sep 2009 22:10:57 +0000 (UTC) Cc: lekktu@gmail.com, dann@ics.uci.edu, lennart.borgman@gmail.com, emacs-devel@gnu.org To: "'Stefan Monnier'" , "'Eli Zaretskii'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Sep 26 00:10:49 2009 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1MrJ04-0007uz-U7 for ged-emacs-devel@m.gmane.org; Sat, 26 Sep 2009 00:10:49 +0200 Original-Received: from localhost ([127.0.0.1]:40520 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MrJ04-0002p7-BO for ged-emacs-devel@m.gmane.org; Fri, 25 Sep 2009 18:10:48 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MrIzs-0002mT-TL for emacs-devel@gnu.org; Fri, 25 Sep 2009 18:10:36 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MrIzn-0002ka-Ae for emacs-devel@gnu.org; Fri, 25 Sep 2009 18:10:36 -0400 Original-Received: from [199.232.76.173] (port=56750 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MrIzn-0002kU-5G for emacs-devel@gnu.org; Fri, 25 Sep 2009 18:10:31 -0400 Original-Received: from rcsinet12.oracle.com ([148.87.113.124]:41924 helo=rgminet12.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MrIzj-0003rB-30; Fri, 25 Sep 2009 18:10:27 -0400 Original-Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n8PMA6sv014126 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 25 Sep 2009 22:10:07 GMT Original-Received: from abhmt016.oracle.com (abhmt016.oracle.com [141.146.116.25]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n8PMAtkM025747; Fri, 25 Sep 2009 22:10:55 GMT Original-Received: from dradamslap1 (/141.144.66.80) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 25 Sep 2009 15:10:20 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: Aco+I+pZd3M26nAKSjCl8Kev6lBOigAAzhUA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: abhmt016.oracle.com [141.146.116.25] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090201.4ABD3FCD.00F3:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:115645 Archived-At: > >> > I'd say "use" covers both kinds of use, but I'll defer > >> > to natives. > >> > >> It's not a question of native speakers. "Use" here refers > >> to what the string is _for_; what it is used for. > > There are often different ways to look at it. E.g. Let's say that > a mode displays two columns of text and set tab-width to half-the > window-width for that purpose; is it "using" tab-width? I'd say yes. > > Similarly, I tend to think that PCL-CVS "uses" > list-buffers-directory in > order to improve the behavior of uniquify. > > In general, variables are a means of communication, and each side of > the communication thinks of itself as "using" the variable > and the other side(s) as "providing" the variable. You _cannot_ know what the variable is for, just by looking at Dired's setting of it. ...without, that is, also reading the comment in Dired that says that it sets it for the benefit of `list-buffers': ;; list-buffers uses this to display the dir being edited in this buffer. The fact that there is such a comment is proof that the setting code does not, by itself, indicate in any way what the variable does - what its effect/purpose is. Why doesn't the setting code help our understanding? Because the variable is set for its consumer - the code that examines (uses) its value. As the comment says, Dired sets it for `list-buffers'. The variable has use only for `list-buffers' (and for similar buffer-listing code). Without that use, setting it has no effect and no purpose. You _can_ tell what the variable is for by looking at the consumer code. Why? Because you can see how it, uh, uses it, concretely. The point is not that consumers depend logically on producers as much as producers depend on consumers, and that variables serve for communication (coupling). That's certainly true, but it doesn't help us describe the variable's purpose or use. The point is what the variable is for. The purpose of the doc string is to tell you what the variable is for, and perhaps a bit about how to use it. This variable's purpose is to affect buffer listings. No foray into the code that sets the value will help you understand that - unless there happens to be a comment there to that effect. It does help to explain that this is a buffer-local variable. That in itself makes it clear that you want to set (and test) the value in the buffer that is to be listed. That is useful info about the producer/consumer relation. So yes, it doesn't hurt to give, in the doc string, the example of setting this locally in a Dired buffer, in order to affect the `File' entry display for that buffer in a buffer listing. But Dired is actually not such a great example, since a directory is also (typically) a file, or is file-like. Using the directory name as the buffer's `File' description is not particularly noteworthy. A better example would be Info, but Info doesn't actually use this variable - instead, we hard-code the treatment of Info buffers in the `list-buffers' code. That code should really be in info.el instead, and it should be used just to set `list-buffers-directory'. IOW, Info should be treated the same way as Dired. BTW, this variable's name is obviously not wonderful. Its value is text that appears in place of a file name in a buffer listing. That has nothing per se to do with directories - we don't list the directory of an Info node's file. It should have been called something like `list-buffers-file-field-text' or `list-buffers-pseudo-file-text'. Too late, perhaps.