bug#9469: buffer-local variables seem to remember previous values

[Drew Adams]

> I think the "as written" bit is mildly confusing, and nearly 
> falls into this trap:
> 
>     In other languages, an expression is text; it has no 
>     other form. In Lisp, an expression is primarily a Lisp
>     object

Indeed.  And I repeat that the misunderstanding comes from not knowing or not
sufficiently appreciating where those objects come from: what creates them.

That is what it would help to repeat/emphasize in the doc (e.g., in the context
of things like `quote', at least via a cross-reference).

Users need of course to understand that `quote' just returns its argument, but
that is not really the problem here, since they can misunderstand "its argument"
per the confusion that Johan referred to (text vs Lisp object).

What users might not get is that the argument that `quote' receives is a Lisp
object that has already been created.  That might not be obvious to someone new
to Lisp.  Especially when written as ', it is easy to misunderstand `quote' as
applying to the textual sexp that follows it, and not to a Lisp object.

The Lisp reader is kind of in the background of user awareness, so the question
of where the Lisp object comes from can mistakenly be answered by thinking that
it is `quote' that creates it based on the text/sexp that follows the '.  That,
I think, is the gotcha that tripped up Le (and he's not alone).

In the case of a literal list argument to `quote', e.g. (quote (a b c)), users
need to understand that the Lisp reader (or loader) creates the list (a b c).

Given that understanding, what can also be missing is that, depending on the
Lisp, the Lisp reader might not create a _new_ list each time it encounters the
sexp "(a b c)".  And in Emacs Lisp it in fact does not create a new list; it
reuses a previously created list, if available.  (Is that always true for Elisp?
What about gc?).

This too is not obvious.  And we can point out that literal strings are treated
differently - the reader does create a new, `eq'-unique string each time it sees
"abc".  The bottom line is that we should communicate the lesson that you should
not depend on the Lisp reader creating a new object each time it reads a sexp.

It would be helpful to mention this and explain that the reader's treatment of
list sexps is similar to its treatment of symbol sexps (names).  The treatment
of symbols is perhaps a bit easier to understand because we introduce the notion
of obarray, and because a symbol itself has an explicit string representation
(its name).

At a minimum, then, the manual's treatment of `quote' (and perhaps other things)
should reference some doc that explains the Lisp reader behavior well.