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: Mon, 20 Apr 2020 17:10:15 +0300 Message-ID: <83368yi6yg.fsf@gnu.org> References: <83tv1finob.fsf@gnu.org> <5c92a765-4502-3063-7f85-302cb1962caf@cs.ucla.edu> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="34483"; 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 Mon Apr 20 16:11:13 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 1jQX8i-0008ro-8E for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 20 Apr 2020 16:11:12 +0200 Original-Received: from localhost ([::1]:36568 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQX8h-0004t1-6b for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 20 Apr 2020 10:11:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43354 helo=eggs1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQX8Z-0004r8-1h for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 10:11:03 -0400 Original-Received: from Debian-exim by eggs1p.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jQX8Y-0006PZ-EF for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 10:11:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:36608) by eggs1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jQX8Y-0006PS-1t for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 10:11:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jQX8X-0002F0-U5 for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 10:11:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 20 Apr 2020 14:11:01 +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.15873918298563 (code B ref 40671); Mon, 20 Apr 2020 14:11:01 +0000 Original-Received: (at 40671) by debbugs.gnu.org; 20 Apr 2020 14:10:29 +0000 Original-Received: from localhost ([127.0.0.1]:48152 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQX80-0002E3-Ue for submit@debbugs.gnu.org; Mon, 20 Apr 2020 10:10:29 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:40248 helo=eggs1p.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQX7y-0002Dn-6g for 40671@debbugs.gnu.org; Mon, 20 Apr 2020 10:10:27 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:47863) by eggs1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQX7s-0004kk-D7; Mon, 20 Apr 2020 10:10:20 -0400 Original-Received: from [176.228.60.248] (port=1321 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jQX7r-0003TQ-4V; Mon, 20 Apr 2020 10:10:20 -0400 In-Reply-To: <5c92a765-4502-3063-7f85-302cb1962caf@cs.ucla.edu> (message from Paul Eggert on Sun, 19 Apr 2020 13:45:07 -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:178710 Archived-At: > Cc: mattiase@acm.org, 40671@debbugs.gnu.org, ke.vigouroux@laposte.net > From: Paul Eggert > 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?