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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9082 in the body.
You can then email your comments to 9082 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: asjo <at> koldfront.dk (Adam Sjøgren)
To: bug-gnu-emacs <at> gnu.org
Subject: Add hints to documentation of car and cdr for (e)lisp newcomers
Date: Thu, 14 Jul 2011 17:03:30 +0200

** Description

Adds hints to the documentation of car and cdr to help newbies remember
which is which.

Saying that (car|cdr) returns the (car|cdr) of a LIST is a little terse
for beginners (probably the only ones looking at the documentation of
such basic functions).

** ChangeLog

2011-07-14  Adam Sjøgren  <asjo <at> koldfront.dk>

	* data.c (car, cdr): add functionality hints to documentation.

** Patch

=== modified file 'src/data.c'
*** src/data.c	2011-07-10 08:20:10 +0000
--- src/data.c	2011-07-14 13:23:02 +0000
*************** DEFUN ("floatp", Ffloatp, Sfloatp, 1, 1,
*** 463,469 ****
  /* Extract and set components of lists */
  
  DEFUN ("car", Fcar, Scar, 1, 1, 0,
!        doc: /* Return the car of LIST.  If arg is nil, return nil.
  Error if arg is not nil and not a cons cell.  See also `car-safe'.
  
  See Info node `(elisp)Cons Cells' for a discussion of related basic
--- 463,469 ----
  /* Extract and set components of lists */
  
  DEFUN ("car", Fcar, Scar, 1, 1, 0,
!        doc: /* Return the car (first element) of LIST.  If arg is nil, return nil.
  Error if arg is not nil and not a cons cell.  See also `car-safe'.
  
  See Info node `(elisp)Cons Cells' for a discussion of related basic
*************** DEFUN ("car-safe", Fcar_safe, Scar_safe,
*** 481,487 ****
  }
  
  DEFUN ("cdr", Fcdr, Scdr, 1, 1, 0,
!        doc: /* Return the cdr of LIST.  If arg is nil, return nil.
  Error if arg is not nil and not a cons cell.  See also `cdr-safe'.
  
  See Info node `(elisp)Cons Cells' for a discussion of related basic
--- 481,487 ----
  }
  
  DEFUN ("cdr", Fcdr, Scdr, 1, 1, 0,
!        doc: /* Return the cdr (rest) of LIST.  If arg is nil, return nil.
  Error if arg is not nil and not a cons cell.  See also `cdr-safe'.
  
  See Info node `(elisp)Cons Cells' for a discussion of related basic

Message #12 received at 9082 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: asjo <at> koldfront.dk (Adam Sjøgren)
Cc: 9082 <at> debbugs.gnu.org
Subject: Re: Add hints to documentation of car and cdr for (e)lisp newcomers
Date: Thu, 14 Jul 2011 20:31:32 +0200

asjo <at> koldfront.dk (Adam Sjøgren) writes:

> 2011-07-14  Adam Sjøgren  <asjo <at> koldfront.dk>
>
> 	* data.c (car, cdr): add functionality hints to documentation.

I've applied your patch to Emacs 24, although...

>   DEFUN ("cdr", Fcdr, Scdr, 1, 1, 0,
> !        doc: /* Return the cdr (rest) of LIST.  If arg is nil, return nil.

this is kinda still wrong-ish.  I mean, you can take the cdr of a cons
cell.  The cdr isn't more `rest' then the car is.  However, since the
documentation says LIST, I guess it's OK.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #15 received at 9082 <at> debbugs.gnu.org (full text, mbox):

From: asjo <at> koldfront.dk (Adam Sjøgren)
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: 9082 <at> debbugs.gnu.org
Subject: Re: Add hints to documentation of car and cdr for (e)lisp newcomers
Date: Thu, 14 Jul 2011 21:19:13 +0200

On Thu, 14 Jul 2011 20:31:32 +0200, Lars wrote:

> asjo <at> koldfront.dk (Adam Sjøgren) writes:

>> * data.c (car, cdr): add functionality hints to documentation.

> I've applied your patch to Emacs 24, although...

Thanks!

>> DEFUN ("cdr", Fcdr, Scdr, 1, 1, 0,
>> !        doc: /* Return the cdr (rest) of LIST.  If arg is nil, return nil.

> this is kinda still wrong-ish.  I mean, you can take the cdr of a cons
> cell.  The cdr isn't more `rest' then the car is.  However, since the
> documentation says LIST, I guess it's OK.

I see what you mean. I just read 'LIST' and looked at wikipedia¹ and...

Please correct it, if possible ;-)


  Best regards,

    Adam

¹ "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

-- 
 "Good car to drive after a war"                              Adam Sjøgren
                                                         asjo <at> koldfront.dk

Message #18 received at 9082 <at> debbugs.gnu.org (full text, mbox):

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: Re: 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).

Message #21 received at 9082 <at> debbugs.gnu.org (full text, mbox):

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

Glenn Morris <rgm <at> gnu.org> writes:

> 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".

And it's still not precise, since "first element" has no meaning if it's
not a list, but just a cons cell.

I've now reverted the patch.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #24 received at 9082 <at> debbugs.gnu.org (full text, mbox):

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

I am sorry, but this is depressing.

Only a newbie would look up the documentation of car and cdr.

This newbie finds this documentation:

  "(car LIST) Return the car of LIST."
  "(cdr LIST) Return the cdr of LIST."

to be unhelpful to the brink of being a slap in the face.

"Nyah, nyah, you don't remember what part of a cons cell is named what -
 and we wo-on't tell you!"

Could you please consider trying to find a way to hint to the casual
lisp user which function does which?

I am perfectly fine with my suggestion being dismissed as meaningless
and wrong, and I agree that this is stuff you learn on your first day of
learning lisp.

But please try to put yourself into the mind of someone who remembers
the concept of those two functions, but can't remember which is which -
a casual user of lisp, looking up the functions in the builtin docs.

Sure, you can quickly try them, or you can figure out why the
(elisp)Cons cells link doesn't work in your emacs-snapshot instance and
read up on it there, or you can find the answer on wikipedia - but just
a little hint in the documentation of the functions we are talking about
would have quenched the frustration instantly.

The target demographic for these texts surely would be someone for whom
"car returns the car, cdr returns the cdr" isn't helping?

I hate to be such a bikeshedder, but I think that you two are way too
good at lisp to have reached the right solution here.

Anyway, thanks for your time.

  Best regards,

    Adam

-- 
 "Good car to drive after a war"                              Adam Sjøgren
                                                         asjo <at> koldfront.dk

Message #27 received at 9082 <at> debbugs.gnu.org (full text, mbox):

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

asjo <at> koldfront.dk (Adam Sjøgren) writes:

> Sure, you can quickly try them, or you can figure out why the
> (elisp)Cons cells link doesn't work in your emacs-snapshot instance and

Funnily enough, I think I fixed that bug earlier today.  :-)

> read up on it there, or you can find the answer on wikipedia - but just
> a little hint in the documentation of the functions we are talking about
> would have quenched the frustration instantly.
>
> The target demographic for these texts surely would be someone for whom
> "car returns the car, cdr returns the cdr" isn't helping?

It's really hard to explain these two functions, because they are so
simple and have little intrinsic meaning.  Which is why they were called
why they're called, and not `first' and `rest' (which also has
proponents).

If a user sees

(setq a '(foo . bar))
(zot (cdr a))

I don't see how looking up `cdr' and seeing "(rest)" really
unconfuses all that much.  Pointing to the manual is the only thing that
will help here, in my opinion.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #30 received at 9082 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>,
	"'Adam "Sjøgren"'" <asjo <at> koldfront.dk>
Cc: 9082 <at> debbugs.gnu.org
Subject: RE: bug#9082: Add hints to documentation of car and cdr for
	(e)lispnewcomers
Date: Thu, 14 Jul 2011 14:20:10 -0700

> It's really hard to explain these two functions, because they are so
> simple and have little intrinsic meaning.  Which is why they 
> were called why they're called, and not `first' and `rest' (which also has
> proponents).

No, that is not the reason why they were called `car' and `cdr'.
http://en.wikipedia.org/wiki/CAR_and_CDR

And no, it's not difficult to describe these two functions.

It's nearly enough to say:

1. `cons' creates a pair (called a "cons cell" or a "cons") from its two
arguments.

2. (car (cons a b)) = a
   (cdr (cons a b)) = b

That's in fact the definition, and it's a pretty good explanation too.

I say "nearly" enough because it also helps to explain more about conses and
list structure (what's shared, what is not, etc.).

Lisp is not a purely functional language, so while #2 above defines these two
functions functionally, it does not describe them in terms of behavior.  Mainly
because it begs the question of `cons', which is not a pure function and which
is where list structure comes into the picture.

If `cons' were simply a constructor in the functional language (or rewrite or
algebra) sense of that word (essentially an undefined function), then #2 above
would suffice.

> If a user sees
> (setq a '(foo . bar))
> (zot (cdr a))
> I don't see how looking up `cdr' and seeing "(rest)" really
> unconfuses all that much.  Pointing to the manual is the only 
> thing that will help here, in my opinion.

Here, I agree with you, Lars.

`rest' does not describe `cdr', especially when `rest' is thought of in terms of
purely functional languages.  Again, the nub is `cons' and the behavior.

It is also true as has been pointed out that the word `rest' is a better fit for
true lists than for conses.

Previous Next

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