From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#40671: [DOC] modify literal objects Date: Sun, 19 Apr 2020 22:21:56 +0300 Message-ID: <838siri8mj.fsf@gnu.org> References: <83tv1finob.fsf@gnu.org> <1E9E4C19-37C2-4E24-91B7-8101F9CFBF35@acm.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="29006"; mail-complaints-to="usenet@ciao.gmane.io" Cc: ke.vigouroux@laposte.net, eggert@cs.ucla.edu, 40671@debbugs.gnu.org To: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Apr 19 21:23:14 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jQFX6-0007Od-MC for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 19 Apr 2020 21:23:12 +0200 Original-Received: from localhost ([::1]:46848 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQFX5-0000zS-Oz for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 19 Apr 2020 15:23:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50264 helo=eggs1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQFWx-0000zK-Kk for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 15:23:04 -0400 Original-Received: from Debian-exim by eggs1p.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jQFWx-0001Ww-0w for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 15:23:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34447) by eggs1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jQFWw-0001W4-KD for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 15:23:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jQFWw-0006UM-A2 for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 15:23:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 19 Apr 2020 19:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 40671 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 40671-submit@debbugs.gnu.org id=B40671.158732413424870 (code B ref 40671); Sun, 19 Apr 2020 19:23:02 +0000 Original-Received: (at 40671) by debbugs.gnu.org; 19 Apr 2020 19:22:14 +0000 Original-Received: from localhost ([127.0.0.1]:45993 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQFWA-0006T4-03 for submit@debbugs.gnu.org; Sun, 19 Apr 2020 15:22:14 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:46910 helo=eggs1p.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQFW8-0006Sr-L3 for 40671@debbugs.gnu.org; Sun, 19 Apr 2020 15:22:13 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:55224) by eggs1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQFW1-0007F5-Qt; Sun, 19 Apr 2020 15:22:05 -0400 Original-Received: from [176.228.60.248] (port=4620 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jQFW0-0005Mg-Ef; Sun, 19 Apr 2020 15:22:05 -0400 In-Reply-To: <1E9E4C19-37C2-4E24-91B7-8101F9CFBF35@acm.org> (message from Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= on Sun, 19 Apr 2020 18:59:55 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:178664 Archived-At: > From: Mattias Engdegård > Date: Sun, 19 Apr 2020 18:59:55 +0200 > Cc: Paul Eggert , 40671@debbugs.gnu.org, > ke.vigouroux@laposte.net > > 19 apr. 2020 kl. 15.56 skrev Eli Zaretskii : > > > 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?