bug#40671: [DOC] modify literal objects

[Eli Zaretskii]

> Cc: 40671-done@debbugs.gnu.org, Kevin Vigouroux <ke.vigouroux@laposte.net>,
>  Eli Zaretskii <eliz@gnu.org>
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Sat, 18 Apr 2020 13:10:30 -0700
> 
> Mattias, thanks for going through the Emacs manual and looking for mistakes 
> in 
> this area. I know it was a pain to do that, since I did something similar in 
> parallel and it was painful for me. I used your patch to crosscheck with my 
> draft (finding omissions on both sides) and installed the resulting patch 
> (attached) into the emacs-27 branch.
> 
> This patch should address the points that Eli raised.

How do you know the patch addresses my concerns, when you didn't even
let me read and comment on it?  What is this rush to go ahead and push
changes when there's clearly some controversy that hasn't yet been
resolved?  Can I somehow convince you not to do that in the future?

> That is, it adds explanations of the issue (both in the intro and
> the reference manual, since the issue also infects the intro), and
> it attempts to change examples only when the changes are needed to
> avoid undefined behavior in Emacs Lisp.

As Štěpán points out, not all of the examples need these changes.
Please revert the changes that aren't needed.

More generally, it is IMO not enough to explain the issue in one
place, and then use non-literal constructs everywhere as if the reader
magically knows or remembers something that is written in a very far
place of the manual.  The effect is to obfuscate the manual without
any explanation right there and then -- which is IMNSHO a very bad
thing, methodologically, because it leaves the readers wondering what
they are missing.

For example, the node "Sets and Lists" now sometimes uses literal
lists and sometimes non-literal ones -- without any explanation why.
Likewise in "Association Lists" and "Sequence Functions".

This is a step backward.  We are making our manual a riddle that the
reader will have to solve.  That is not how good manuals are written.

>  @example
>  @group
> -(delq 'a '(a b c)) @equiv{} (cdr '(a b c))
> +(equal
> + (delq 'a (list 'a 'b 'c))
> + (cdr (list 'a 'b 'c)))
>  @end group

And here you simply changed the meaning of the example: @equiv{} is
not the same as 'equal'.

Bottom line: the extra explanations about the danger of using literal
lists in some situations are a good addition to the manual, but most
of the replacements elsewhere of literal lists with non-literal ones
are not -- unless we also add in each case some text which explains
why we use 'list', 'cons', 'vector', etc, instead of literal
constants.

Please fix these deficiencies.

Thanks in advance.