bug#40671: [DOC] modify literal objects

[Drew Adams]

> > Don't say "constant".  Say "don't try to change it".
> 
> That's too long and awkward a phrase for use in lots
> of places around the manual. We need a simple noun
> phrase to describe the concept; this is Documentation 101.

Giving it an undefined/unexplained name doesn't describe
it at all.

Giving it an existing name (e.g. "constant"), which means
something else, indirectly describes it incorrectly.

Why do we need to say this in "lots of places around
the manual"?  Explain the gotcha in one place, and if
need to refer to that explanation elsewhere then do so
(link). 

> One possible substitute is "literal object", as Mattias
> pointed out.  Another possibility is "immutable object".
> Perhaps others might be better.

As I explained, none of those correspond to what I think
the gotcha is.

> > The only cases that are problematic are those where
> > you can think your code modifies something (anew)
> > when in fact it might not.
> 
> No, that's not the only issue. If you modify some of
> these "constants" (or "literal objects" or whatever
> term you like), the behavior is undefined: Emacs can
> crash or remove your home directory or whatever.

If Emacs can crash or remove your home directory,
that's a bug, IMO.  We don't document bugs, and we
certainly shouldn't let Emacs crash and just tell
you not to do XYZ because of that.

Saying the behavior in some case is not defined means
(usually) that we're not going to support/guarantee
what the behavior is in that case, and we're not
going to detail/say what it is.  Saying some behavior
is undefined is never (in my experience) done knowing
it crashes the program.

> There is no checking.

If that's what's meant then say that.

The explanation of the gotcha should, IMO, include a
simple example of quoting a list: '(1 2 3), and then
modifying some of that list structure.

Say what can happen, e.g. with byte-compilation, and
how that's different from what one might expect if
'(1 2 3) is incorrectly thought of as always creating
new list structure each time that code is evaluated.

Maybe say that just reading the '(1 2 3) creates a
list, and that thereafter that same list is used by
the byte compiler.

The point in showing a simple list example is to
help make clear what's going on.  More importantly,
the quoted-list version of the gotcha is the common
one.

I don't want to belabor this.  If you don't get what
I'm saying then perhaps someone else will be willing
to explain it better than I.  Or if what I've said
is unclear also to others, or is judged wrong, then
please forget about it.

To me, it's pretty simple in terms of effect: You
write '(1 2 3), and you mistakenly think you've
essentially written code that does what (list 1 2 3)
does: creates a new list each time the code it's in
gets evaluated.

Maybe that '(1 2 3) code is in a context where it
(looks like it) gets evaluated more than once.
You think you're getting a new list (new conses)
each time.  Some other code modifies the list (e.g.
using setcar).  You think that code is modifying
a new list each time, but it's not - it's modifying
the same cons.  Gotcha.

There are no doubt other scenarios that exhibit
essentially the same gotcha.  But I don't think
it's necessary to detail them all.  What's needed
is to provide the warning, some general description
of the problem, and/or a simple example (using a
list).