bug#40671: [DOC] modify literal objects

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

> > It's about code that always creates new list
> > structure, versus code that might create new
> > list structure only sometimes (e.g. the first
> > time it's encountered).
> 
> Could we call them "interned values"? Like "interned strings" in some
> programming languages. And then say "don't try to modify them please".
> 
> The "sometimes" aspect is a semantic snag, but it's certainly better
> than calling them constant.
> 
> "literal values" is also an option, but that definition seems limiting.

You're replying to a message of mine from a
while back.  I agree with the limitation or
difficulty of communicating the "sometimes"
aspect.  And I agree that the message for users
should be "don't try to modify them" (even
though the "them" isn't detailed).

My own opinion is to avoid mention of any such
name: constant, literal, interned this-or-that.
Better to keep it vague, and just sketch the
problem and say that the behavior is undefined.

IMO, the message for users for the quoted-list
gotcha should be to not assume that code that
has a quoted list in it creates a new list
whenever you might think that that code (Lisp
source or byte-compiled) gets evaluated.

`quote' returns its arg unevaluated, but it's
not always clear by looking at the source code
just when or how many times a quoted list might
get evaluated.  That's undefined, so assume
nothing about it.  In particular, the behavior
can differ for the same source code, depending
on whether it's interpreted or byte-compiled.

A simple example could suffice, to make that
point.

If it helps, we can also say, for the example,
that the source-code quoted list might, in
effect, get replaced by its value when it's
read or byte-compiled, so the same cons cells
(not new list structure) might get reused each
time the resulting code gets evaluated.

And because of that possibility you're advised
not to try to modify such a list.

Yes, there are other examples of the problem,
besides quoted lists.  Like the Common Lisp
doc, we could list some of them, without
giving more examples or going into detail.

Or we could give a second simple example,
perhaps with a string literal.

What's important, I think, is to (1) get
across the general idea/problem, (2) give
some idea how to recognize situations where
the gotcha can arise, and make clear that
you cannot depend on the behavior.

There's no prevention of the gotcha, e.g. by
raising an error systematically.  You just
have to learn to recognize the possibility of
trying to modify something that may have
become, at some point, effectively
unmodifiable - and not do that.