From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Arthur Miller Newsgroups: gmane.emacs.devel Subject: Lispref add-to-list - doc is unnecessary convoluted Date: Fri, 04 Dec 2020 03:17:19 +0100 Message-ID: Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="26472"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Dec 04 03:18:49 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 1kl0gK-0006mU-0W for ged-emacs-devel@m.gmane-mx.org; Fri, 04 Dec 2020 03:18:48 +0100 Original-Received: from localhost ([::1]:55922 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kl0gJ-0008K4-1c for ged-emacs-devel@m.gmane-mx.org; Thu, 03 Dec 2020 21:18:47 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56740) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kl0f0-0007oO-W3 for emacs-devel@gnu.org; Thu, 03 Dec 2020 21:17:27 -0500 Original-Received: from mail-am6eur05olkn2098.outbound.protection.outlook.com ([40.92.91.98]:3041 helo=EUR05-AM6-obe.outbound.protection.outlook.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kl0ey-0003KP-2G for emacs-devel@gnu.org; Thu, 03 Dec 2020 21:17:26 -0500 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Z9YQLnsKjw5qXtd4CDuZQY5Ma8HPMpKdKYDMVh7Dk8OnYoG6IEbFGULxqTU19vfmWA06rbCPW6x1B0qZ95b1HgdqKePoHhvchokbzrTVsotRThtxKvN0ns/tLcjCwGzEOJp+Ua3P9FkEl3NS6kP3M9x7WtrTWKThzIo3Asbnsg+GVpADMB5CTtHgWpcmIn8kwgXZiR3k3hm/9uyzcp7HvKV3+uz6AMD2iPMMZvTAEDMalV8hqldW3gwQhaVPYj05pmVESeLOmVvqsRiE+O96Wj3+LTRw0Z+ygPILlcAKFOMoIhfh0QjK7nYt42K5QOhl0jVgUvnGoE3rma7bzFG/+Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=ArLLuGKJA6Dh0z88axHecarrlbomsZ+J/xv1UEC/M6M=; b=gI5zvE8M4LAwQ/xDzGr7/P92bDtetDMvln9t9t3swKZ5N0toPoJCJNPo+7M3BCb4o5dzNBkFk7pa/MFARbZvVZA+EdIetuSIkYGOj/9UKf5MircSKjfYG8WGfuWel2LZRH4oRuRoo2lBIkGipxL/ZTRa2L5I8sO2TQKwRAykNmM/IWu+crRmeaq45+r0FRA0yB2skNd0CuxRxp7j+dRPpmlaSbbRFClcRa3CZZ2qYn/Q0mxkH5oWHm1RuSzC32GgzVC7MO/pQXdfsfl0jEHP7nN8kxqMgkp9bx5Qj9A18pOh8KsT4OGwLd8p/Mh92453CXez6FTDtOwPYDROK3orKQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=live.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=ArLLuGKJA6Dh0z88axHecarrlbomsZ+J/xv1UEC/M6M=; b=hct1xNgO45QWiEeBu1Q4B6hgr+vqkav0jwNnIYf0pAg7hjoUwtnm1yr+FPL8MwKAZ294ekYI9f3BKzvhI8yqM2e2Q/zJJ9AZIzROfAba8v/Q7xcOAxeZ0Yg5/ACIEeU8W1yNkNXFP2C0D7Y28wkpp6Y1j+CTW2nk+FwTGqHxXXmcoNv1IqNKJZvGKniTWsA4G+jiMu19igoYDjrpq68Fh/5PAtgt33hwl2+K5gHOA9Ljj5yeXaQT3Vrtt1/WLih/mhlHvT7A/HM1RxRwTvxPs71Wpb6tAmVs/j54tfmIOWSwj/0P9oVAs//4Mv8RKL7IcZhbednN1qibB2Gix4K8LA== Original-Received: from VI1EUR05FT010.eop-eur05.prod.protection.outlook.com (2a01:111:e400:fc12::53) by VI1EUR05HT199.eop-eur05.prod.protection.outlook.com (2a01:111:e400:fc12::288) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3632.17; Fri, 4 Dec 2020 02:17:21 +0000 Original-Received: from AM0PR06MB6577.eurprd06.prod.outlook.com (2a01:111:e400:fc12::43) by VI1EUR05FT010.mail.protection.outlook.com (2a01:111:e400:fc12::159) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3632.17 via Frontend Transport; Fri, 4 Dec 2020 02:17:21 +0000 X-IncomingTopHeaderMarker: OriginalChecksum:A63B6CE40BBF01FDC8DFF80B9B7F6A9C69165A507C439E33B6C11FD5652C0810; UpperCasedChecksum:B5E470FC028C4924862051C05D3B2A44953C0CECBF9589260F589E81A60FEA3F; SizeAsReceived:7236; Count:43 Original-Received: from AM0PR06MB6577.eurprd06.prod.outlook.com ([fe80::9487:8c7d:da00:4993]) by AM0PR06MB6577.eurprd06.prod.outlook.com ([fe80::9487:8c7d:da00:4993%7]) with mapi id 15.20.3632.018; Fri, 4 Dec 2020 02:17:20 +0000 X-TMN: [s6dRlwJNPNzse6sic7Xdo25B16Nbjf1S] X-ClientProxiedBy: AM6PR10CA0056.EURPRD10.PROD.OUTLOOK.COM (2603:10a6:209:80::33) To AM0PR06MB6577.eurprd06.prod.outlook.com (2603:10a6:208:19a::23) X-Microsoft-Original-Message-ID: <87lfeeb9hs.fsf@live.com> X-MS-Exchange-MessageSentRepresentingType: 1 Original-Received: from pascal.homepc (90.230.29.56) by AM6PR10CA0056.EURPRD10.PROD.OUTLOOK.COM (2603:10a6:209:80::33) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3632.17 via Frontend Transport; Fri, 4 Dec 2020 02:17:20 +0000 X-MS-PublicTrafficType: Email X-IncomingHeaderCount: 43 X-EOPAttributedMessage: 0 X-MS-Office365-Filtering-Correlation-Id: 22cec7e8-49e4-4f8d-d50c-08d897fabad3 X-MS-TrafficTypeDiagnostic: VI1EUR05HT199: X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: F0ToJe4rW/O3qHf8LlhfbPEcNUKoBeHAEPguuUp6OrCf3Z1NEufODQtD4h41kTY23PgKWBMLAj0Rhu0IVx2EW0YZDbfjfiKKIgcfoHNB7sKdFHES8p6kjlP8SFk3CbAz+kP2AdlQE/SSckeol/uen41ndEEpxh4UFdfCQ+L3uXLbCpipjRtJ0RCdveTlqvF2Xx9TYW4yEILVOCbvZRU+iQ== X-MS-Exchange-AntiSpam-MessageData: JaisOarP/XaTFU0ZmrwS+CfoqbaVrPmIv273U6qC9uTBfzMxaG6sKe9wXvAk9pFJdoa4FbVmePLteJRYMjA2GaNzctKwXivfPii2qphE9D/G6gDnJEdgtE0lNAvJXH7CE2TOQ1z43Tdg8FZx6HrYDg== X-OriginatorOrg: live.com X-MS-Exchange-CrossTenant-Network-Message-Id: 22cec7e8-49e4-4f8d-d50c-08d897fabad3 X-MS-Exchange-CrossTenant-OriginalArrivalTime: 04 Dec 2020 02:17:20.8004 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-AuthSource: VI1EUR05FT010.eop-eur05.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: Internet X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1EUR05HT199 Received-SPF: pass client-ip=40.92.91.98; envelope-from=arthur.miller@live.com; helo=EUR05-AM6-obe.outbound.protection.outlook.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, MSGID_FROM_MTA_HEADER=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-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:260264 Archived-At: --=-=-= Content-Type: text/plain Function: add-to-list symbol element &optional append compare-fn This function sets the variable symbol by consing element onto the old value, if element is not already a member of that value. It returns the resulting list, whether updated or not. The value of symbol had better be a list already before the call. add-to-list uses compare-fn to compare element against existing list members; if compare-fn is nil, it uses equal. Normally, if element is added, it is added to the front of symbol, but if the optional argument append is non-nil, it is added at the end. The argument symbol is not implicitly quoted; add-to-list is an ordinary function, like set and unlike setq. Quote the argument yourself if that is what you want. Do not use this function when symbol refers to a lexical variable. I think this doc is unnecessary convoluted and I don't see reason why it describes the implementation. That first sentence make something so simple as add-to-list sound so complicated for some reason when you read it, and requires one to think twice through what it say (at least me). Other functions does not do so, so why this one? I don't think it is necessary since docs anyway says how it add to list (front/back) kist a three sentences further. 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'. I hope I don't hurt anyone's feelings; I dont' know who wrote it, but I would like to suggest a slight modification, patch included. I am not native english speaker, so if you agree to change it, somebody please look through it. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=add-to-list-doc.patch diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index ae793d5e15..c7f6a46aeb 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -761,22 +761,19 @@ List Variables Two functions modify lists that are the values of variables. -@defun add-to-list symbol element &optional append compare-fn -This function sets the variable @var{symbol} by consing @var{element} -onto the old value, if @var{element} is not already a member of that -value. It returns the resulting list, whether updated or not. The -value of @var{symbol} had better be a list already before the call. -@code{add-to-list} uses @var{compare-fn} to compare @var{element} -against existing list members; if @var{compare-fn} is @code{nil}, it -uses @code{equal}. +@defun add-to-list list element &optional append compare-fn +This function adds the @var{element} to a list @var{list} if +@var{element} is not already a member of that value. It returns the +resulting list, whether updated or not. @code{add-to-list} uses +@var{compare-fn} to compare @var{element} against existing list +members; if @var{compare-fn} is @code{nil}, it uses @code{equal}. Normally, if @var{element} is added, it is added to the front of -@var{symbol}, but if the optional argument @var{append} is +@var{list}, but if the optional argument @var{append} is non-@code{nil}, it is added at the end. -The argument @var{symbol} is not implicitly quoted; @code{add-to-list} -is an ordinary function, like @code{set} and unlike @code{setq}. Quote -the argument yourself if that is what you want. +The argument @var{list} is not implicitly quoted; @code{add-to-list} +is an ordinary function, like @code{set} and unlike @code{setq}. Do not use this function when @var{symbol} refers to a lexical variable. --=-=-=--