bug#40671: [DOC] modify literal objects

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

> >> Drew mentioned his dislike for the term "safe" AFAIR
> >
> > I don't recall saying that, but I may have.  Not
> > sure what's meant here.  I objected to using
> > "dangerous", as if the gotcha was generally
> > hazardous to life.
> 
> Would "unsafe mutations" be better?

I didn't really want to get into this with you
guys.  I just wanted to reply to Michael's
message.  But...

I'd prefer that we speak of "modification",
not "mutation".  "Mutation" has a connotation
of something happening on its own.  If that
were the case then we wouldn't be trying to
tell people not to do something!

I'm not a big fan of "safe" (or, especially,
"dangerous"), unless it's about human safety
(e.g. an airline maintenance manual).

I'd prefer that we just tell users that if
they do certain things then the behavior of
their code _might not be what they expect_.
Or that the behavior is "undefined".  And
let it go at that.

What's important is to give them some idea
of _what_ it is that we're telling them not
to do.  I don't have an example, but I think
a simple quoted-list example can get the point
across.  And then you can say something about
strings or whatever, if you like, without
bothering with more examples.

My advice: don't try to explain too well
just what happens.  See if you can get the
general point across without any exhaustive
rundown of a bunch of different cases or
trying to be too exact.

If a user understands that internal Lisp
structures (objects) can get created by
(1) the Lisp reader, (2) the interpreter, and
(3) the byte compiler, and if s?he understands
that what's seen in the source code does not
necessarily correspond to when a corresponding
Lisp object gets created, then s?he'll get it.

Just when, and how many times does the source
code of a quoted list result in a new cons?
You can't really know.  When it's read?
byte-compiled?

A new Lisp user thinks in terms of interpreted
source code.  Seeing a quoted list, s?he thinks
that a new cons is created each time it's read,
interpreted, or byte-compiled.  But that may
not (typically does not) happen.  If you modify
the cons that resulted from a source-code quoted
list then that _same_ cons might be baked into
the internal code thereafter.