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 16:56:52 +0300 Message-ID: <83tv1finob.fsf@gnu.org> References: 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="111386"; mail-complaints-to="usenet@ciao.gmane.io" Cc: mattiase@acm.org, 40671@debbugs.gnu.org, ke.vigouroux@laposte.net To: Paul Eggert Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Apr 19 15:58:12 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 1jQASZ-000Ssu-Na for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 19 Apr 2020 15:58:11 +0200 Original-Received: from localhost ([::1]:41998 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQASY-0007Ow-QY for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 19 Apr 2020 09:58:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35054) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQASR-0007OX-Bn for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 09:58:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jQASQ-0007Oq-TL for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 09:58:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34076) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jQASQ-0007Od-Gv for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 09:58:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jQASQ-0000rD-3x for bug-gnu-emacs@gnu.org; Sun, 19 Apr 2020 09:58: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 13:58: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.15873046283234 (code B ref 40671); Sun, 19 Apr 2020 13:58:02 +0000 Original-Received: (at 40671) by debbugs.gnu.org; 19 Apr 2020 13:57:08 +0000 Original-Received: from localhost ([127.0.0.1]:45621 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQARY-0000q6-FK for submit@debbugs.gnu.org; Sun, 19 Apr 2020 09:57:08 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:59960) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQARX-0000pt-9o for 40671@debbugs.gnu.org; Sun, 19 Apr 2020 09:57:07 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:51649) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQARQ-0005fg-Bh; Sun, 19 Apr 2020 09:57:00 -0400 Original-Received: from [176.228.60.248] (port=4598 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jQARP-0003cN-5u; Sun, 19 Apr 2020 09:56:59 -0400 In-Reply-To: (message from Paul Eggert on Sat, 18 Apr 2020 13:10:30 -0700) 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:178635 Archived-At: > Cc: 40671-done@debbugs.gnu.org, Kevin Vigouroux , > Eli Zaretskii > From: Paul Eggert > Date: Sat, 18 Apr 2020 13:10:30 -0700 > > Mattias, thanks for going through the Emacs manual and looking for mistakes in > this area. I know it was a pain to do that, since I did something similar in > parallel and it was painful for me. I used your patch to crosscheck with my > draft (finding omissions on both sides) and installed the resulting patch > (attached) into the emacs-27 branch. > > This patch should address the points that Eli raised. How do you know the patch addresses my concerns, when you didn't even let me read and comment on it? What is this rush to go ahead and push changes when there's clearly some controversy that hasn't yet been resolved? Can I somehow convince you not to do that in the future? > That is, it adds explanations of the issue (both in the intro and > the reference manual, since the issue also infects the intro), and > it attempts to change examples only when the changes are needed to > avoid undefined behavior in Emacs Lisp. As Štěpán points out, not all of the examples need these changes. Please revert the changes that aren't needed. More generally, it is IMO not enough to explain the issue in one place, and then use non-literal constructs everywhere as if the reader magically knows or remembers something that is written in a very far place of the manual. The effect is to obfuscate the manual without any explanation right there and then -- which is IMNSHO a very bad thing, methodologically, because it leaves the readers wondering what they are missing. 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 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. > @example > @group > -(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) > +(equal > + (delq 'a (list 'a 'b 'c)) > + (cdr (list 'a 'b 'c))) > @end group And here you simply changed the meaning of the example: @equiv{} is not the same as 'equal'. Bottom line: the extra explanations about the danger of using literal lists in some situations are a good addition to the manual, but most of the replacements elsewhere of literal lists with non-literal ones are not -- unless we also add in each case some text which explains why we use 'list', 'cons', 'vector', etc, instead of literal constants. Please fix these deficiencies. Thanks in advance.