GNU bug report logs - #9082
Add hints to documentation of car and cdr for (e)lisp newcomers

Previous Next

Full log

View this message in rfc822 format

From: Glenn Morris <rgm <at> gnu.org>
To: asjo <at> koldfront.dk (Adam Sjøgren)
Cc: Lars Magne Ingebrigtsen <larsi <at> gnus.org>, 9082 <at> debbugs.gnu.org
Subject: bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers
Date: Thu, 14 Jul 2011 15:47:43 -0400

>>> DEFUN ("cdr", Fcdr, Scdr, 1, 1, 0,
>>> !        doc: /* Return the cdr (rest) of LIST.  If arg is nil, return nil.
[...]
> ¹ "When cons cells are used to implement singly linked lists (rather
>    than trees and other more complicated structures), the car operation
>    returns the first element of the list, while cdr returns the rest of
>    the list." - http://en.wikipedia.org/wiki/CAR_and_CDR

To me, "rest" means nothing with no context.
It's fine to say: "A returns the first element, and B the rest."
But just saying on its own "B returns the rest" with no reference to A
means nothing.
I might say "B returns everything but the first element".

But really, one should read the Lisp intro or something if one does not
know what car and cdr mean. The doc string of such fundamental functions
shouldn't be expected to bootstrap from zero knowledge IMO.

Oh, I see there is already a reference to the lisp manual in these doc
strings. So personally I don't think any change was needed...

Also to complete my bitching, this should be marked "tiny change" since
we don't have an Emacs assignment (only a Gnus one).

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.