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

From: [email-masked] (Adam Sjøgren)
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
                                                         [email-masked]