Subject: bug#40671: [DOC] modify literal objects

From: Paul Eggert <[email-masked]>
Date: Sun, 19 Apr 2020 14:16:35 -0700

On 4/19/20 2:01 PM, Drew Adams wrote:
>> distinguish between constant objects (which the
>> program should not change) and mutable objects
>> (which the program can change).
> That's just not what "constant" means.

What does "constant" mean to you? It's not clear.

> And I
> suspect that your _uses_ of _not_ "mutable" will
> still be for things that we really want to say
> you probably _should not_ change, and not that
> you _cannot_ change them.

Your suspicion is correct. In the current emacs-27 documentation, "mutable" 
means you can change the object, "constant" means you should not change it. It's 
intended to be documentation that is simple and consistent and tells programmers 
what they can do without worrying (change a mutable object), and what they 
shouldn't do (try to change a constant).

Of course the documentation could have a more-complex discussion of the various 
ways that an object could be "constant". The object could be in read-only memory 
enforced by the hardware and operating system, or there could be a run-time 
check by the Emacs interpreter, or there could be no check at all and you can 
change the constant with the program behaving erratically afterwards, or there 
are other possibilities. If you'd like to add text along those lines to the new 
section "Constants and Mutability" please feel free to suggest something. The 
point is to make that section useful for Emacs Lisp programmers, after all.

>  This can give the
> impression  that if you _can_ change something
> (the real meaning of "mutable") then there's no
> reason you shouldn't change it.

I'm not following. Even if I've created an object with the 'cons' function there 
may be very good pragmatic reasons for me to not invoke setcar and setcdr on it, 
as otherwise my program's actions will be scrambled. However, from the Emacs 
lisp point of view such a cons is still mutable.

If you propose specific text for the manual, no doubt your point will become 
clearer.