bug#14926: 24.3.50; Warning "`make-variable-buffer-local' should be called at toplevel"

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

> > > "Warning: `make-variable-buffer-local' not called at toplevel"

> > > would have the same learning experience, without saying
> > > "should be...", which is wrong and confusing to people who
> > > know what they're doing.
> >
> > Sounds right.  Can someone make that change, plase?
> 
> Done. Of course, it won't remotely satisfy the OP.

Right.  It warns people not to use `make-variable-buffer-local'
except at top level.  Which is wrong.  Top level is irrelevant
to the proper use of `make-variable-buffer-local'.

By Stefan's admission, the problem this warning aims to solve is
a user who might be confusing `make-variable-buffer-local' with
`make-local-variable'.

His heuristic is presumably that IF `make-variable-buffer-local'
is used somewhere other than at top level THEN it is likely that
the user has confused the two functions, and `make-local-variable'
might be more appropriate.

It is the THEN part of that sentence, not the IF part, that is
the proper message for the user.

Assuming that the heuristic is good, the "warning" should really
draw the user's attention, not to "top level", but to
`make-local-variable' (which it does not mention).

Non top-levelness is only the **means by which the compiler**
detects a situation where the user might need help.  The warning
as proposed does not provide the help.  At all.

Think of what the user needs, not what the heuristic does.

You think you've found a good way to detect a case where the user
needs to be informed about `make-variable-buffer-local' vs
`make-local-variable'.  Great.  So tell the user about that, not
about how you figured out that s?he might be confused (= not at
top level).

If you want to issue a warning based on this heuristic, the 
message to the user should be to suggest that s?he might want
to use `make-local-variable' instead.  Don't even mention "top
level".  Just tell the user to consider using `make-local-variable'.

A useful message would even point to a doc section clarifying
the difference between the two functions.