RE: make-variable-buffer-local change

["Drew Adams" <drew.adams@oracle.com>]

> >> > 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.