From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Robin Tarsiger Newsgroups: gmane.emacs.devel Subject: Re: Lispref add-to-list - doc is unnecessary convoluted Date: Thu, 3 Dec 2020 20:36:49 -0600 Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="26422"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.12.0 Cc: emacs-devel@gnu.org To: Arthur Miller Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Dec 04 03:37:41 2020 Return-path: Envelope-to: ged-emacs-devel@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 1kl0yb-0006n2-6y for ged-emacs-devel@m.gmane-mx.org; Fri, 04 Dec 2020 03:37:41 +0100 Original-Received: from localhost ([::1]:60586 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kl0ya-0003uT-7F for ged-emacs-devel@m.gmane-mx.org; Thu, 03 Dec 2020 21:37:40 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59766) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kl0xq-0003TI-8g for emacs-devel@gnu.org; Thu, 03 Dec 2020 21:36:54 -0500 Original-Received: from out3-smtp.messagingengine.com ([66.111.4.27]:43169) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kl0xn-0001We-AL for emacs-devel@gnu.org; Thu, 03 Dec 2020 21:36:53 -0500 Original-Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.nyi.internal (Postfix) with ESMTP id 8A4DD5C01BB; Thu, 3 Dec 2020 21:36:49 -0500 (EST) Original-Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Thu, 03 Dec 2020 21:36:49 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm1; bh=W9+9gKS4u56G+uQ15pyx3VvAzqqn/Mqi4XzSsicmC Kk=; b=DcibrpTUv1OzYNSIxuMlmOGNhQNOE/Xi29Oxom3kokHjVDjpk+G+RYXMB p0k13nDJSjSe3FNO7gqeMm0M1gMrU1pSMHLubEQBNqRJ3/Ej5rjO/v1iCbuB9dAM InkchXZaDUhabcUuX9eSdjAFxD4QIB6GMB3zrP8Uv+8drvSVh4CXXlu0xx9DIc/J zkzwIouEcdzkwuXHfZ+gfgx4/H8X34XUPuh3mBB9B3+JdkA/m5LV0hKuNCHQciCo 13JrpIkm4ajpxkmjcW+dNbyMYKtmAYjT9il7s+5fjeAhyk/KPufXswq3IXzG2hT6 n81klW0qp/v7lOo9R1Tv/YBKeQ4Eg== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedujedrudeijedghedtucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepvfhfhffukffffgggjggtgfesthekredttdefjeenucfhrhhomheptfhosghi nhcuvfgrrhhsihhgvghruceorhhtthesuggrshihrghtihgurggvrdgtohhmqeenucggtf frrghtthgvrhhnpedvudfggeffieegkeeuueefvdekffekheevvddtgeevledthefhkeef fefgkefgkeenucfkphepjeeirddvheefrdejhedrfeegnecuvehluhhsthgvrhfuihiivg eptdenucfrrghrrghmpehmrghilhhfrhhomheprhhtthesuggrshihrghtihgurggvrdgt ohhm X-ME-Proxy: Original-Received: from [192.168.1.65] (76-253-75-34.lightspeed.austtx.sbcglobal.net [76.253.75.34]) by mail.messagingengine.com (Postfix) with ESMTPA id 97F361080057; Thu, 3 Dec 2020 21:36:48 -0500 (EST) Autocrypt: addr=rtt@dasyatidae.com; prefer-encrypt=mutual; keydata= mQINBFlZ32YBEADE52MDC4u9v99gDRaMycG7kJQ1fz5pmRUQtLPfMYUWOkAVBC/dgpUsVdtG MnYpEl6cdVaRBfSNbJG0TPyHuM3DxiPMoBsnTGbf8BY43ZvRnk6Ibku/yv48m17crQFRvJaJ fr7e1z+cKcNqrnfYtuf5sJ+I5X3lqtKQcHAMNqYboRVLPWv7XlM1H34Mnzmb9lJAlowvXBU3 UaRe0D71vytKza/jtoQQsJeGVSQiuNElRbUns/jzpZgiQ+zRDcZQyPACsWzWnnsZbhqdxiwD IACKeIyqpgGyxbccXqe2iwJ/V3q/acl4rgX31eU1kaBuEh/Kc8Zz3uEG9SjHJMIcwm+nR5E4 KI0p2vecHU09scQoGDCwwSXqWtv5GaFU7Akf+CKaYDQ0Z2+iDnHZUU9U8kpqEn+Ys0ChjLeC ya85OJ37T4M8KUbEPshOI6kuiWmGHjxyRJKkr0nQztS6swr1Fb0iIZeX/fplHP9g+LBh+lJE iZQfRytz84AjPz74qdFwh5qVa8VqOQ0CJirevFCYVcwf/1gyGC44oVgWN64fMxBg4WsubCjB CBPACqZrKT8uahPObgzhJ4EIROoOSY3u6tWCK6/GSGiDPLHyLkRWYwvO+neoI9mUub+ZC+29 JFrKnbtIudRXSb1t5OsbDgQmnYm/H6Df16NhX8ikqrnkmknnZQARAQABtCNSb2JpbiBUYXJz aWdlciA8cnR0QGRhc3lhdGlkYWUuY29tPokCUAQTAQgAOgIbAQIeAQIXgAQLCQcDBBUKCQgD FgIAFiEEEgc4poGjw In-Reply-To: Content-Language: en-US-large Received-SPF: none client-ip=66.111.4.27; envelope-from=rtt@dasyatidae.com; helo=out3-smtp.messagingengine.com X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, NICE_REPLY_A=-0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_NONE=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:260266 Archived-At: Arthur Miller wrote: > I think it is more clear to use word 'list' instead of 'symbol' (element > is a symbol too for example). Not least because docs later says: "better > be a list". It clarifies intentions, and hopefully removes the need to say > things like 'better be a list'. The first argument is not itself a list. The value (as in symbol-value) of the first argument is expected to be a list. The first sentence of the documentation has that many levels of indirection because that's how many levels of indirection there actually are in the behavior of the function. Your new text does not describe it correctly. "cons onto" a list is more specific than "add to" in terms of where the new element winds up, though the paragraph describing the APPEND argument also mentions this, so it's not strictly necessary. But while looking at this, I notice that the C-h f docstring for add-to-list that I see on my Emacs names the first argument more clearly as LIST-VAR (neither the correct-but-overbroad SYMBOL nor the incorrect LIST), and has the first sentence "Add ELEMENT to the value of LIST-VAR if it isn't there yet", which seems to hit both of the points you're dissatisfied with. Might that be a better starting point if making the elisp Info entry more readable is desired? -RTT