GNU bug report logs - #40671
[DOC] modify literal objects

Previous Next

Full log

Message #36 received at 40671 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: ke.vigouroux <at> laposte.net, Paul Eggert <eggert <at> cs.ucla.edu>,
 40671 <at> debbugs.gnu.org
Subject: Re: [DOC] modify literal objects
Date: Sun, 19 Apr 2020 18:59:55 +0200

19 apr. 2020 kl. 15.56 skrev Eli Zaretskii <eliz <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.