bug#40671: [DOC] modify literal objects

[Paul Eggert]

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.

0001-Minor-fixups-for-mutability-doc.patch
Description: Text Data