bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

[Adam Sjøgren]

** 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@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

bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

[Lars Magne Ingebrigtsen]

asjo@koldfront.dk (Adam Sjøgren) writes:

> 2011-07-14  Adam Sjøgren  <asjo@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/

bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

[Adam Sjøgren]

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

> asjo@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@koldfront.dk

bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

[Glenn Morris]

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

bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

[Lars Magne Ingebrigtsen]

Glenn Morris <rgm@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/

bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

[Adam Sjøgren]

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@koldfront.dk

bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers

[Lars Magne Ingebrigtsen]

asjo@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/

bug#9082: Add hints to documentation of car and cdr for (e)lispnewcomers

[Drew Adams]

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