bug#40671: [DOC] modify literal objects

[Dmitry Gutov]

Hi Paul,

On 09.05.2020 09:10, Paul Eggert wrote:
> On 5/5/20 5:38 AM, Dmitry Gutov wrote:
>
> > In any case, none of my objections here are strong ones. How about you take the
> > proposed patch and update it as you see fit? As long as "constant values" don't
> > make a comeback, I'm good.
> OK, attached is a draft patch to emacs-27. Although it doesn't go as far as your
> patch, it does keep some of it, and in particular it gets rid of the
> introduction of the term "constant" to describe objects that should not be
> changed. It also omits the "Dangerous" that Drew objected to, and gives an
> example of a term that was formerly mutable but is now something that you should
> not change.

It's an improvement, but still I don't understand your choice.

Starting with:

  Some Lisp objects should never change.  For example, you can create
  a new number by calculating one, but you cannot modify the value of an
  existing number.

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

Then, this passage is still confusing, and it doesn't have to be:

  Although numbers never change and all markers are mutable, a type
  can be a hybrid with some members mutable and other members not.

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. Why make the mental image harder than we have to?

Further down:

  A mutable object stops being mutable if it is part of an expression
  that is evaluated.  For example,
  in @code{(eval (list 'quote (list 1)))}
  the list @code{(1)} was mutable when it was created, but it should not
  be changed after it was part of an argument to @code{eval}.

But the list object didn't change, just an outside reference to its head 
was created, and that made it "possibly shared", depending on how the 
aggregated value is subsequently used.

And further:

  ...whereas the
  call @code{(make-string 3 ?a)} yields a mutable string that can be
  changed via later calls to @code{aset}

The opposite of "mutable" is "immutable". Are quoted strings immutable? 
They are not.

Overall the phrase "that might be shared" is a good replacement. Why not 
keep to it? The rest of the patch doesn't try so hard to force the new 
definitions anymore, so your new meaning of "mutable" doesn't seem 
indispensable.