Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

["Adam Sjøgren" <asjo@koldfront.dk>]

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