From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Christopher Dimech Newsgroups: gmane.emacs.devel Subject: Re: Lispref add-to-list - doc is unnecessary convoluted Date: Fri, 4 Dec 2020 03:27:07 +0100 Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="40538"; mail-complaints-to="usenet@ciao.gmane.io" 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:31:37 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 1kl0si-000AS7-OJ for ged-emacs-devel@m.gmane-mx.org; Fri, 04 Dec 2020 03:31:36 +0100 Original-Received: from localhost ([::1]:58178 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kl0sh-0002Oo-IZ for ged-emacs-devel@m.gmane-mx.org; Thu, 03 Dec 2020 21:31:35 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57990) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kl0oT-0001gp-Vf for emacs-devel@gnu.org; Thu, 03 Dec 2020 21:27:13 -0500 Original-Received: from mout.gmx.net ([212.227.17.22]:46587) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kl0oR-0006ap-TJ for emacs-devel@gnu.org; Thu, 03 Dec 2020 21:27:13 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1607048827; bh=i2D6ZTWnG2ni8Qlg0DtrafzHim9FO5Lw8jQ8JCfWZ7c=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=ChioK5Urv9AsAk52eYkehdxqYrHRdeV01XFp+TaMSb3cMQRf6zEjLVGTxy1SfP03s 2LbLviBd1I3iPma4MgDaUV641/SnP0hJxyCo1TzhmXYRoaU9xYQ+O8S+xBHaXaygm6 eL+6IRHZsJaxCkGzBTnN/ROooYcJxJPhg34Bl0xg= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from [213.165.168.94] ([213.165.168.94]) by web-mail.gmx.net (3c-app-mailcom-bs11.server.lan [172.19.170.179]) (via HTTP); Fri, 4 Dec 2020 03:27:07 +0100 Importance: normal Sensitivity: Normal In-Reply-To: X-UI-Message-Type: mail X-Priority: 3 X-Provags-ID: V03:K1:ZaHdLPHiSA4Xv2NvWc5sYNFb8mJGDp45wGIU11AmvmTzoTY5srP8/q0rYjZuyDnxWtkiJ Vh96KkG2LEm9umVIct5Sz/k8O5lN4gJXCptD0/LPgvDaiVEJzY20D/mYAuFLBzWQoFL4g/5gxbbc c2mnO9dYTiXkSh6AzpUB7959XnAV+91nbus3GuUz0qAhdZTByeh1FQAM6W+qT09KKLRHGh+1ZQRN QRgPWV1PluQnu7+7Iv7fV99u7dkL2+0rvaR3hD7bo2wrioyzse4vx6uZajVO/Q0vJOTeZooRa7cd ds= X-UI-Out-Filterresults: notjunk:1;V03:K0:OCXAN3aD7h4=:+LWX/XKKyHZ/5AmpXP/u4G nhZt2xzDW/6CKFEr+1vesRsrTNnKyglOApaj1LIRQgzL2I8Epsp//u6KQ+rcMgx0rTqJ60CPD sXzEPVsNDdwBEUdvBUmA4pHizSlVCH9sTnc6gyjfU6g4J5BAoQuWRvGwrr7QAn2xKZ5nRhbWs k9oRoB6H+OAqREiOWFFD+jObuXXFTs3LzEUzfjfEPhMvnSCab3hMgwU7xCGgunnThCRTe5Ooj fD9SJjzmUJo9hNY3TInOC20NtWgWknbtSzRiTCaQAflAaRglThXWSp+7BJWsT4PIqYwmglb05 8R20VJ98BEAhPkLUPC/vE8plfhyJ6jaG6V5n7IkwkXWa/+E3q6EDhf6/6ZeazEwyHmZtaYOAg GKTPwMZn+e4RwlkQQMBE5xvrSpEuJ5Li1mYVAAYs1k3vKXqMrbDigFWBK3ggEvME1KBpK2P+O ptLiAiZwQOwadL9Pi+ReLezvgIIL5uBkmwot83BCe3KhgscKyG08K8JvVe5FIbpYBCXz9DKi1 3PNIHOE7/BFgfJEgEhoNXNXYv4Gt/P65zzUmvNRUUQUuFu6yb8tjNbFAvLDRErvswAsGrQKdu 4lnaMoPWUrAiw= Received-SPF: pass client-ip=212.227.17.22; envelope-from=dimech@gmx.com; helo=mout.gmx.net 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, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=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:260265 Archived-At: > Sent: Friday, December 04, 2020 at 3:17 AM > From: "Arthur Miller" > To: emacs-devel@gnu.org > Subject: Lispref add-to-list - doc is unnecessary convoluted > > Function: add-to-list symbol element &optional append compare-fn > > This function sets the variable symbol by consing element onto the o= ld 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 el= ement 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, b= ut 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 ordi= nary function, like set and unlike setq. Quote the argument yourself if th= at 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). I concur. > 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 s= ay > things like 'better be a list'. Agree > 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. Not hurt. I shall read it and report back. Cheers C*