all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Add hints to documentation of car and cdr for (e)lisp newcomers - take 2
@ 2021-07-14 15:05 Adam Sjøgren
  2021-07-14 15:36 ` Andreas Schwab
                   ` (3 more replies)
  0 siblings, 4 replies; 32+ messages in thread
From: Adam Sjøgren @ 2021-07-14 15:05 UTC (permalink / raw)
  To: emacs-devel

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




^ permalink raw reply	[flat|nested] 32+ messages in thread

end of thread, other threads:[~2021-07-16 14:38 UTC | newest]

Thread overview: 32+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-07-14 15:05 Add hints to documentation of car and cdr for (e)lisp newcomers - take 2 Adam Sjøgren
2021-07-14 15:36 ` Andreas Schwab
2021-07-14 15:48 ` tomas
2021-07-14 15:50 ` Eli Zaretskii
2021-07-14 16:03   ` Lars Ingebrigtsen
2021-07-14 16:13     ` Eli Zaretskii
2021-07-15  4:34       ` Lars Ingebrigtsen
2021-07-14 23:49     ` Stefan Kangas
2021-07-15  4:38       ` Lars Ingebrigtsen
2021-07-15 11:39         ` Stefan Kangas
2021-07-15 14:14           ` Eli Zaretskii
2021-07-15 15:02             ` Tim Cross
2021-07-15 15:41               ` Stefan Monnier
2021-07-15 15:21             ` Stefan Monnier
2021-07-15 15:26               ` Yuan Fu
2021-07-15 15:52                 ` Eduardo Ochs
2021-07-15 15:44               ` Lars Ingebrigtsen
2021-07-15 15:57                 ` Eli Zaretskii
2021-07-16  0:22                   ` Stefan Monnier
2021-07-16  2:08                     ` Jean-Christophe Helary
2021-07-16 13:22                       ` Stefan Monnier
2021-07-16 14:38                         ` Basil L. Contovounesios
2021-07-16  7:00                     ` Eli Zaretskii
2021-07-15 15:53               ` Eli Zaretskii
2021-07-15 16:17                 ` Jean-Christophe Helary
2021-07-15 16:30                   ` Lars Ingebrigtsen
2021-07-15 16:57                     ` Eli Zaretskii
2021-07-15 17:01                       ` Lars Ingebrigtsen
2021-07-15 17:07                         ` Eli Zaretskii
2021-07-15 20:54                         ` Stefan Kangas
2021-07-15 21:11                           ` Lars Ingebrigtsen
2021-07-14 16:37 ` [External] : " Drew Adams

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.