bug#40671: [DOC] modify literal objects

[Paul Eggert]

On 5/9/20 8:13 PM, Dmitry Gutov wrote:

> You start talking about objects that "should [not] change". And give an 
> example
> of an object that _cannot_ change.

That's easily altered to also give an example of an object that should not
change; see attached patch.

> I could understand it if it was describing an existing type system of the
> language, or implementation internals, but this is a purely imaginary type
> system.

objects.texi already talks about the Emacs Lisp type system and specifically
mentions strings, conses, etc. as types. Even if one considers the Emacs Lisp
type system to be "imaginary", it's reasonable to use the documentation's
already-existing terminology here.

> the list object didn't change, just an outside reference to its head was
> created,

The attached patch alters the example so that the list object does change (or at
least tries to).

> The opposite of "mutable" is "immutable". Are string literals immutable? They 
> are
> not.

They might be mutable, and they might not be. The documentation deliberately
doesn't say, because we don't want to document the details (they have changed in
the past and are likely to change in the future).

> Overall the phrase "that might be shared" is a good replacement. Why not keep 
> to
> it?

Because it's not an accurate statement of the problem. The set of objects that
might be shared differs from the set of objects that should not change. The
Mutability node focuses on the latter set of objects, and gives the former as an
example but it is not the only sort of object that should not change.

> your new meaning of "mutable" doesn't seem indispensable.

That bar is too high, as hardly anything in the manual is *indispensable*. Ihe
notion of mutability is good to have in the manual, as it reduces confusion and
helps in documentation elsewhere. That's good enough.

I'm attaching two patches. The first are the changes mentioned above, and the
second is a single patch that combines the first patch with the changes I
previously proposed.

0001-Update-mutability-doc.patch
Description: Text Data

0001-Don-t-use-constant-for-values-you-shouldn-t-change.patch
Description: Text Data