From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: =?utf-8?Q?Adam_Sj=C3=B8gren?= Newsgroups: gmane.emacs.devel Subject: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2 Date: Wed, 14 Jul 2021 17:05:24 +0200 Organization: koldfront - analysis & revolution, Copenhagen, Denmark Message-ID: <8735shrl57.fsf@tullinup.koldfront.dk> 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="21386"; 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 Cancel-Lock: sha1:0cpM5a0atFAzLw6fM9hq57QDTxk= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Jul 14 17:18:26 2021 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 1m3geY-0005NI-FN for ged-emacs-devel@m.gmane-mx.org; Wed, 14 Jul 2021 17:18:26 +0200 Original-Received: from localhost ([::1]:47598 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m3geX-0004Zh-Fz for ged-emacs-devel@m.gmane-mx.org; Wed, 14 Jul 2021 11:18:25 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50756) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m3gS9-0000dR-8t for emacs-devel@gnu.org; Wed, 14 Jul 2021 11:05:37 -0400 Original-Received: from ciao.gmane.io ([116.202.254.214]:34234) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m3gS5-00027C-HS for emacs-devel@gnu.org; Wed, 14 Jul 2021 11:05:36 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1m3gS3-00099s-JL for emacs-devel@gnu.org; Wed, 14 Jul 2021 17:05:31 +0200 X-Injected-Via-Gmane: http://gmane.org/ X-Face: )qY&CseJ?.:=8F#^~GcSA?F=9eu'{KAFfL1C3/A&:nE?PW\i65"ba0NS)97, Q(^@xk}n4Ou rPuR#V8I(J_@~H($[ym:`K_+]*kjvW>xH5jbgLBVFGXY:(#4P>zVBklLbdL&XxL\M)%T}3S/IS9lMJ ^St'=VZBR 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:271213 Archived-At: Ten years ago I was confused by the documentation of car and cdr: ,---- | (car LIST) | | Return the car of LIST. If arg is nil, return nil. `---- ,---- | (cdr LIST) | | Return the cdr of LIST. If arg is nil, return nil. `---- Which is which?!? And I suggested a (bogus) improvement¹ based on reading too much into the four letters L I S and T in the descriptions excerpted above. While trying to write some basic elisp recently, I again realized that I had forgotten which of car and cdr is which. Based on one of the replies to my previous documentation improvement attempt, I saw that there might be a way to improve the documentation for my newbie case, without introducing something that is factually wrong. How about: ,---- | (car '(a . b)) | | Return a. If arg is nil, return nil. `---- ,---- | (cdr '(a . b)) | | Return b. If arg is nil, return nil. `---- ? This variant of the documentation contains more information: what part of the cons cell is returned by either function. Also it doesn't use the four letters L I S and T, which might lead somebody who hasn't read and memorized the Lisp intro, like me, to think that what car/cdr works on is actually a LIST. What do you think? Hm, I realize now that you can call car and cdr on things that don't look like '(a . b), so maybe this suggestion is as bad as the old one. Maybe I should just try to stick to the mnemonic that car comes before cdr alphabetically. Or what about: ,---- | (car LIST) | | Return the car of LIST, eg if LIST is '(a . b) return a. If arg is nil, return nil. `---- ,---- | (cdr LIST) | | Return the cdr of LIST, eg if LIST is '(a . b) return b. If arg is nil, return nil. `---- Ducking, Adam ¹ https://debbugs.gnu.org/cgi/bugreport.cgi?bug=9082 -- "You know, I *thought* earth's gravity felt Adam Sjøgren exceptionally strong today." asjo@koldfront.dk