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.
> 
> Would replacing "use" with "set" solve this problem?

You missed the point. We don't want to talk about places where the value is set.
What's important is what the variable is for.

We can give an example of where it is used, if we like, but not where it is set
(pretty much irrelevant). It so happens that the place of consumption
(buffer-listing code) can be far from the place it is set (e.g. Dired).

What is important is to let users know that they can set it for use by
buffer-listing code.

> > > > Please correct the doc string accordingly.
> > > 
> > > Don't hesitate to send a patch and I'll commit it ASAP.
> > 
> > Just get rid of "Dired, shell and other modes use this variable."
> 
> Sorry, I happen to disagree.  This is important information for such
> an obscure feature.  The alternative is let the user grep the whole
> lot of Lisp sources.

You missed the point.

What's most important about this variable is what it is for, not where in the
existing code it happens to be set. _Why_ it is set is important. Which is to
say _what it does_ is important - what you can use it for.

What this variable does is provide text to use for non-file buffers, when
buffers are listed along with their associated file names. It is the consumer of
this feature, buffer-listing code, that needs the feature.

It is for that use that code (anywhere) sets the variable. It's not for Dired or
shell that Dired and shell set this variable - it's for buffer-listing purposes
by Buffer Menu and the `Buffers' menus.

As I mentioned to Juanma off list, we could add something about the use of the
variable, if that helps to clarify things. But what we add shouldn't be about
which code happens to set the variable, but rather which code lists buffers and
thus makes use of the variable.

I suggested adding something like this, if people think something additional is
needed:

"For example, in the Buffer Menu (`C-x C-b'), if the local value for a given
non-file buffer is non-nil, then it is shown in the `File' column for that
buffer."

(Perhaps "it" should be replaced with "that value", to be clearer.)

That describes (gives an example of) what this variable does and how to use it:
set its local value for code that lists buffers and their "files"
(descriptions).