From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#40671: [DOC] modify literal objects Date: Sun, 19 Apr 2020 22:32:36 -0700 (PDT) Message-ID: References: <87v9lzmdrw.fsf@laposte.net> <57532862-f6ec-84b6-13af-8a8985366ff0@cs.ucla.edu> <127084e8-c62a-ec8c-5d40-8c4280861519@cs.ucla.edu> <566aa1bf-444d-4cff-aed8-5b83fcd60107@default> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="117387"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Kevin Vigouroux , 40671@debbugs.gnu.org To: Paul Eggert , Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Apr 20 07:33: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 1jQP3Q-000UQw-ND for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 20 Apr 2020 07:33:12 +0200 Original-Received: from localhost ([::1]:57766 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQP3P-0002mG-Pc for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 20 Apr 2020 01:33:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56332 helo=eggs1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQP3H-0002lc-K6 for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 01:33:04 -0400 Original-Received: from Debian-exim by eggs1p.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jQP3G-0000n5-DI for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 01:33:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34897) by eggs1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jQP3G-0000mP-1b for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 01:33:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jQP3F-0004BF-TE for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2020 01:33:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 20 Apr 2020 05:33: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.158736077916059 (code B ref 40671); Mon, 20 Apr 2020 05:33:01 +0000 Original-Received: (at 40671) by debbugs.gnu.org; 20 Apr 2020 05:32:59 +0000 Original-Received: from localhost ([127.0.0.1]:46443 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQP3C-0004Ax-S5 for submit@debbugs.gnu.org; Mon, 20 Apr 2020 01:32:59 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:47772) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQP3B-0004Ak-3u for 40671@debbugs.gnu.org; Mon, 20 Apr 2020 01:32:57 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 03K5TqUI144114; Mon, 20 Apr 2020 05:32:46 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=+a2HOSSmhoCTeZuodn09wubpUpB8lM+8eZfhYf/IiDw=; b=S4ZVWB1hGO4rUR5APk2IESdLfsIeXmvLbl7YJ3qKEnFlD/SqAV6/Rdy6UsDflcxO+Y/5 JfIhSF9GkWkQuMpZbj7YQqG060nXwHRQ6JFkIeFVOjRw2Ld6vwLzq71EvMc3xGrBGlSZ ZGL5QCN6afgEnbrkYgkCx3yO8JTw9D6TLE+lBMaFfBXxA3qmSqO9DjTva8Gy3jqaZwo9 ohfZXDcdLqFf7m27533w/IelvRWvLv3ZFl5nyrLqVjQhEBF8zn1ag0hPvzdFIkC56bhS alciZM1jowdx0eIqO26FqMdo4J8r+iFhuQmlPq4Lw7ddF/p9RGb1w+h9Wh7RQUUJOjRU VA== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2120.oracle.com with ESMTP id 30ft6mvwga-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 20 Apr 2020 05:32:46 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 03K5RVpw029003; Mon, 20 Apr 2020 05:32:45 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserp3030.oracle.com with ESMTP id 30gb3pqfxr-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 20 Apr 2020 05:32:45 +0000 Original-Received: from abhmp0006.oracle.com (abhmp0006.oracle.com [141.146.116.12]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 03K5WbB3011170; Mon, 20 Apr 2020 05:32:37 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4966.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9596 signatures=668686 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 malwarescore=0 spamscore=0 adultscore=0 mlxlogscore=999 phishscore=0 suspectscore=0 bulkscore=0 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2004200048 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9596 signatures=668686 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 bulkscore=0 priorityscore=1501 impostorscore=0 adultscore=0 phishscore=0 lowpriorityscore=0 malwarescore=0 clxscore=1015 mlxlogscore=999 mlxscore=0 spamscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2003020000 definitions=main-2004200048 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:178699 Archived-At: > > Don't say "constant". Say "don't try to change it". >=20 > That's too long and awkward a phrase for use in lots > of places around the manual. We need a simple noun > phrase to describe the concept; this is Documentation 101. Giving it an undefined/unexplained name doesn't describe it at all. Giving it an existing name (e.g. "constant"), which means something else, indirectly describes it incorrectly. Why do we need to say this in "lots of places around the manual"? Explain the gotcha in one place, and if need to refer to that explanation elsewhere then do so (link).=20 > One possible substitute is "literal object", as Mattias > pointed out. Another possibility is "immutable object". > Perhaps others might be better. As I explained, none of those correspond to what I think the gotcha is. > > The only cases that are problematic are those where > > you can think your code modifies something (anew) > > when in fact it might not. >=20 > No, that's not the only issue. If you modify some of > these "constants" (or "literal objects" or whatever > term you like), the behavior is undefined: Emacs can > crash or remove your home directory or whatever. If Emacs can crash or remove your home directory, that's a bug, IMO. We don't document bugs, and we certainly shouldn't let Emacs crash and just tell you not to do XYZ because of that. Saying the behavior in some case is not defined means (usually) that we're not going to support/guarantee what the behavior is in that case, and we're not going to detail/say what it is. Saying some behavior is undefined is never (in my experience) done knowing it crashes the program. > There is no checking. If that's what's meant then say that. The explanation of the gotcha should, IMO, include a simple example of quoting a list: '(1 2 3), and then modifying some of that list structure. Say what can happen, e.g. with byte-compilation, and how that's different from what one might expect if '(1 2 3) is incorrectly thought of as always creating new list structure each time that code is evaluated. Maybe say that just reading the '(1 2 3) creates a list, and that thereafter that same list is used by the byte compiler. The point in showing a simple list example is to help make clear what's going on. More importantly, the quoted-list version of the gotcha is the common one. I don't want to belabor this. If you don't get what I'm saying then perhaps someone else will be willing to explain it better than I. Or if what I've said is unclear also to others, or is judged wrong, then please forget about it. To me, it's pretty simple in terms of effect: You write '(1 2 3), and you mistakenly think you've essentially written code that does what (list 1 2 3) does: creates a new list each time the code it's in gets evaluated. Maybe that '(1 2 3) code is in a context where it (looks like it) gets evaluated more than once. You think you're getting a new list (new conses) each time. Some other code modifies the list (e.g. using setcar). You think that code is modifying a new list each time, but it's not - it's modifying the same cons. Gotcha. There are no doubt other scenarios that exhibit essentially the same gotcha. But I don't think it's necessary to detail them all. What's needed is to provide the warning, some general description of the problem, and/or a simple example (using a list).