bug#40671: [DOC] modify literal objects

[Paul Eggert]

On 4/18/20 2:54 PM, Drew Adams wrote:

> "should be applied only to @dfn{mutable} lists,
> that is, lists constructed via @code{cons},
> @code{list} or similar operations."
>
> That's not a usual meaning of "mutable".  Your
> "that is" makes clear what you mean, sort of, I
> suppose.  That part is clear enough, but it's
> not a good "definition" of "mutable".
>
> 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).

I think we're mostly in agreement here, it's just that it can be difficult to 
state things clearly in a reference manual. Let me try to explain a bit further.

As far as Elisp is concerned, it's OK to apply destructive operations to list 
structures that are created only sometimes (e.g., the first time it's 
encountered), so long as these structures have been created dynamically by the 
program. That is, the key notion is not whether the program is implementing 
hash-consing on its own (where it's a bad idea to modify already-existing 
structures but is valid as far as Elisp is concerned); the key notion here is 
whether the program is diving into the Lisp interpreter's data structures and 
attempting to change those data structures on the fly (the program shouldn't do 
that, as the results are unpredictable and Emacs might crash).

> A quoted list, which you call "constant", is in
> fact mutable in some contexts.

Yes, but we cannot easily document where and when those contexts might be, and 
it would be a disservice to our users if we tried to document what happens 
exactly, partly because of the complexity and partly because the byte-compiler 
might change in the future. Instead, we should simply say that one should not 
modify the data structures that quoted lists return.

> An immutable list would be one you couldn't ever
> change - it would truly be a constant.  That can
> be true for the result of byte-compiling a quoted
> list.

We can talk about the distinction between a "true constant" and a "constant" in 
an introductory section, but in the rest of the manual it's simpler to merely 
distinguish between constant objects (which the program should not change) and 
mutable objects (which the program can change). That is, in most of the manual 
there's no reason to distinguish between the two: modifying a constant is 
trouble, and programs shouldn't do it. In the introductory section we can talk 
about what happens if programs try to modify a constant anyway.

> "However, the other arguments (all but the last)
> must be mutable lists."
>
> "MUST" means you CANNOT do otherwise.

I changed it to "should".

> BTW, "a quoted constant list" is a bit poorly
> worded, as well.

I changed that to "constant list".

> FWIW, Common Lisp doesn't talk about mutable
> or immutable lists (or other objects):
>
>   "The consequences are undefined if literal
>    objects (including quoted objects) are
>    destructively modified."
>
> Undefined.  They CAN sometimes be destructively
> modified.

Yes, that's the idea I'm trying to capture here as well, with the changes I 
installed today.

Thanks for your comments.