bug#40671: [DOC] modify literal objects

[Eli Zaretskii <eliz@gnu.org>]

> Cc: mattiase@acm.org, 40671@debbugs.gnu.org, ke.vigouroux@laposte.net
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Sun, 19 Apr 2020 13:45:07 -0700
> 
> > 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 was in response to your request to not change examples if the examples 
> didn't strictly need the changes. Although I preferred Mattias's original 
> proposal because it switched to the (list ...) style more uniformly, the patch I 
> installed mixed the '(...) and (list ...) styles because I thought that was what 
> you were asking for.
> 
> I installed the attached patch, which attempts to address this issue by adding 
> comments that try to explain why (list ...) is needed sometimes.

This is better, thanks.  Although my feeling that we complicated what
used to be a simple section is still here.

> However, in 
> hindsight perhaps we should go back to the style used in Mattias's proposal, as 
> it's simpler and more consistent and doesn't distract the reader from the focus 
> of the documentation. Going back to Mattias's style would let us remove some of 
> the comments that the attached patch inserts.

I think consistency should take a back seat in these situations.
Clarity and easiness of reading and understanding are much more
important.

> As you note, it's not essential that the list be modifiable in this particular 
> example. That being said, the documentation should not suggest that it's OK to 
> use a destructive operation like delq on a constant, so further improvements 
> would be helpful here if someone can find the time.

But that's exactly the disagreement between us: you think that each
example must be perfect in that it follows all of the principles ever
mentioned anywhere in the manual, and shouldn't go anywhere near the
places which we explain elsewhere are, or might be, dangerous.  The
problem with that is that if you want to be absolutely correct and
rigorous, you will more often than not be unable to say anything, or
will produce code samples that are so arcane to the beginner that they
will squarely miss their point.  Witness your dialogue with Michael
Heerdegen about related issues.

I think there's no need to assign such crucial importance to every
example.  If it is easy to make the example more correct by small
changes, we should consider doing that.  But adding the likes of
copy-list to an example that's supposed to show how to delete a list
member is IMO a terrible overkill, and makes the example harder to
understand: a reader who just learned about making and modifying lists
suddenly needs to know what copy-list does (e.g., is it a deep copy or
not?).  IMO and IME, this kind of rigor is self-defeating, unless it
comes in a special section marked "Advanced" or somesuch.

Bottom line: IMO the manual should introduce the material gradually;
it is okay to defer some subtle aspects to later sections, and
initially simply disregard them.  E.g., in a section that describes
arithmetic operators like '+' in C to someone who is supposed to be a
C beginner, you won't right away talk about integer overflow and the
subsequent danger of crashing the system, and you won't tell the
reader "don't ever use '+', use INT_ADD_WRAPV instead", nor will you
replace examples that use '+' with that macro, would you?