bug#40671: [DOC] modify literal objects

[Mattias Engdegård]

19 apr. 2020 kl. 15.56 skrev Eli Zaretskii <eliz@gnu.org>:

> 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.

Eli, maybe that is stretching it a bit? Paul's (and my) changes are far from 
perfect but they did aim to do no harm. Surely we all prefer correct to simple 
and wrong. Mistakes must and will be fixed, naturally.

Your point about not surprising the user about inconsistencies in examples is 
entirely fair, and we should definitely explain these issues more clearly and 
in the right order. However, it doesn't mean that the status quo ante was 
better: not only did the manual set bad examples in many places, it even 
managed to warn sternly about non-constant arguments to nconc right after an 
example which did precisely that.

What about we add a separate section about literals of all types, why they 
should be treated as immutable even though mutation currently isn't detected or 
disallowed at runtime, and recommended ways of coping with it (constructor 
functions, copy-sequence)? It would serve as a point of reference for all 
sections describing destructive operations. There is also a need for some 
cautionary text in the backquote section.

I'd volunteer to write it all but won't do the work just to have it shot down 
on general principles. It's not like I'm expecting a blank cheque, but we'd 
need to agree on the approach first.