bug#40671: [DOC] modify literal objects

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Sun, 19 Apr 2020 18:59:55 +0200
> Cc: Paul Eggert <eggert@cs.ucla.edu>, 40671@debbugs.gnu.org,
>         ke.vigouroux@laposte.net
> 
> 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.

The problem is that the changes were pushed before they could be
reviewed and commented.  No one said anything about meaning to do
harm, but mistakes do happen, and a good way to avoid mistakes is to
let peer review take its course.  Rushing a commit doesn't allow to
make the changes better by considering aspects that the original
committer was unaware of, or where he/she is biased or lacks some
knowledge or experience that others can contribute.

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

I stand by what I wrote: the status quo ante was better.

A manual is not a mathematical paper, where everything should be
rigorous all the way from the first page to the last.  A good manual
introduces the material gradually, and makes simplifications to avoid
dumping too much stuff on the reader at once.  So yes, it is entirely
legitimate to show simplified examples, and at some later point say
that those simple examples have pitfalls, and explain those pitfalls.
There's absolutely no requirement to be 110% correct everywhere in the
manual, because that will make the manual hard to read and understand,
and eventually will shoot us in the foot.

This is, of course, my opinion.  Your opinions might be different, and
maybe you could convince me in some of the cases.  But for this to
happen, we need to talk, and you (or Paul) need to present the
arguments that aim at changing my mind (or change your own).  Is it
too much to ask to let the discussion proceed?  If these matters are
important, then we should give their discussion our best shot, so that
the net result is absolutely the best we could come up with -- and
that means it should incorporate the different views and experiences
of most or all the participants.

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

I don't think I understand the proposal enough to answer the question.
Wed already have a section about these matters, and the additions that
Paul made there are more or less uncontroversial, I think, and
generally consider a Good Thing.  What do you suggest in addition to
that?