bug#40671: [DOC] modify literal objects

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 2599 bytes --]

On 5/11/20 6:59 PM, Dmitry Gutov wrote:

> I think that's exactly what a "constraint" means: something that is enforced.

Not necessarily. In some software systems constraints are not enforced. (Use
Google to search for "unenforced constraints", which can be quite the thing in
the database world.) But I am straying from the documentation issue.

> The symbol-name example? I'm not sure it's really important to
> warn about this one in particular.

OK, but then you also write:

>  When one tries to
> describe "unsafe" things to do, they don't just give a few examples, they
> usually try to cover all cases.

... and symbol-name is one of the cases.

As far as the bigger project (cover all the cases) goes, I don't know how
feasible that would be. I suppose someone could take that on as a further task.
In the attached patch I did add one more example, of calling the copy-sequence
function, but there would be lots more examples where that came from.

> Inventing a name for such values doesn't help if the user doesn't have enough
> knowledge to avoid all members of this set. Or is "part of an expression that is
> evaluated" after all the test we'll be teaching?

No, it's not the only way that something can be a constant. This is why the
(symbol-name 'cons) example is relevant: it yields a string that has never been
"part of an expression that is evaluated".

> By the way, I have read last two paragraphs of that section now. C and
> "constants" are still there.

It's appropriate to talk about constants in the footnote that mentions languages
that have constants. And the footnote is helpful, because it documents the core
issue that prompted this long thread: different languages/traditions mean
different things by the word "constant" and/or "immutable", and the footnote
makes it clear that the documentation's "objects that should not be changed"
follows the Common Lisp / C tradition, not the Python / JavaScript tradition.

That being said, it'd be helpful if the footnote mentions both "constants" and
"immutable objects" if only to remind readers of relevant buzzwords. So I did
that in the attached patch.

> I'm curious to see the discussion about actually making this error at runtime in
> one of the next Emacs version.

Me too. That's for a later thread, one that I'd like to get rolling instead of
worrying about the minor details in the current doc. To help get things rolling
I installed the patch that I proposed earlier, followed by the attached minor
patch that attempt to address the abovementioned issues. I plan to look at
improving the runtime checking next.

[-- Attachment #2: 0001-Minor-fixups-for-mutability-doc.patch --]
[-- Type: text/x-patch, Size: 2686 bytes --]

From b48ab743a861b8041518ce7459bde51c3dd02ee0 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 16 May 2020 18:16:23 -0700
Subject: [PATCH] Minor fixups for mutability doc

* doc/lispref/objects.texi (Mutability): Minor fixups in
response to a comment by Dmitry Gutov (Bug#40671#477).
---
 doc/lispref/objects.texi | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 136213ad66..5c5f89eb43 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -2381,7 +2381,7 @@ that for two strings to be equal, they have the same text properties.
 
   Some Lisp objects should never change.  For example, the Lisp
 expression @code{"aaa"} yields a string, but you should not change
-its contents.  Indeed, some objects cannot be changed; for example,
+its contents.  And some objects cannot be changed; for example,
 although you can create a new number by calculating one, Lisp provides
 no operation to change the value of an existing number.
 
@@ -2393,11 +2393,10 @@ point to somewhere else.
   Although numbers never change and all markers are mutable,
 some types have members some of which are mutable and others not.  These
 types include conses, vectors, and strings.  For example,
-although @code{"aaa"} yields a string that should not be changed,
-@code{(make-string 3 ?a)} yields a mutable string that can be
-changed via later calls to @code{aset}.  Another example:
-@code{(symbol-name 'cons)} yields a string @code{"cons"} that should
-not be changed.
+although @code{"cons"} and @code{(symbol-name 'cons)} both yield
+strings that should not be changed, @code{(copy-sequence "cons")} and
+@code{(make-string 3 ?a)} both yield mutable strings that can be
+changed via later calls to @code{aset}.
 
   A mutable object stops being mutable if it is part of an expression
 that is evaluated.  For example:
@@ -2419,9 +2418,9 @@ becomes mutable afterwards.
 changed, the resulting behavior is undefined: the Lisp interpreter
 might signal an error, or it might crash or behave unpredictably in
 other ways.@footnote{This is the behavior specified for languages like
-Common Lisp and C, and it differs from the behavior of languages like
+Common Lisp and C for constants, and this differs from languages like
 JavaScript and Python where an interpreter is required to signal an
-error if a program attempts to change a constant.  Ideally the Emacs
+error if a program attempts to change an immutable object.  Ideally the Emacs
 Lisp interpreter will evolve in latter direction.}
 
   When similar constants occur as parts of a program, the Lisp
-- 
2.17.1