bug#40671: [DOC] modify literal objects

[Paul Eggert]

On 5/10/20 5:00 PM, Michael Heerdegen wrote:

> Are there any classes of "types" where all members are always mutable?

Markers, for one. (This is mentioned in the previous paragraph.) There are
others. We needn't list them all here.

> Second point: you mix up objects vs. object evaluation.  For conses you
> speak about the objects, for symbols about the binding (i.e. the result
> of the evaluation).  Conses can also be evaluated (most programs are
> conses), but that's surely not what you want to describe.  I would not
> say symbols are mutable.  Symbols are constant AFAICT, their bindings
> are not (variables are not constant).

All good points. The simplest fix is to not mention symbol bindings here, as
they're a complicated topic. Their mutability issues can be documented later, if
someone wants to tackle the subject.

> FWIW, I would feel better about the word "mutable" if you would
> introduce the term like "safely mutable", and then say that we call it
> just "mutable" in the following sections because this is shorter.  Drew
> mentioned his dislike for the term "safe" AFAIR but I think "my Emacs
> won't crash if I follow this" vs. "it can crash" describes some kind of
> safety.  Ignore if this comment is irrelevant because this is already
> done or treated otherwise.

I think that's pretty much already done, since the definition of "mutable" says
"it is safe to change their values". I'd rather not use the term "safely
mutable" everywhere, as I don't want the manual to push the idea of "safely
mutable" as opposed to "mutable"; instead, I want the manual to look forward to
a future version where objects are either mutable or are immutable (and the
latter is checked by the interpreter).

>> +  When the same value appears multiple times in a program, the Lisp
>> +interpreter might save time or space by reusing existing values or
>> +their components.  For example, @code{(eq "abc" "abc")} returns
> 
> I think we call "values" what evaluation of expressions yields, so
> values don't appear in a program (to be read).

They can if one feeds the values into 'eval', which runs part of a program. And
'read' can read programs. So I'm not sure I get the distinction.

> Is it always the interpreter that
> does this mapping?

This section is written at a high level and uses "interpreter" to refer to the
whole Emacs Lisp system. (This usage is longstanding in the manual.) So if any
mapping is being done, it's by the "interpreter" in that sense.

> "Same syntax" is not good as well:

I don't see that phrase used in the manual. I assume you meant "same values"?

>    (eq (list 1 2 3) (list 1 2 3))
> 
> doesn't provoke the pitfall you warn about, but your wording doesn't
> make clear why the one case is ok and the other is not.  Maybe it's
> again as simple as saying something about objects as being part of a
> program?

I changed it to use "parts of a program" and I can changed the "values" to
"constants".

Further patch attached; it also attempts to address the issues raised by Dmitry
and Drew recently. I'm also attaching a single patch that accumulates it into
all the patches proposed for emacs-27.

0001-doc-lispref-objects.texi-Mutability-More-tweaking.patch
Description: Text Data

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