Re: The doc-strings for car and cdr are insulting.

[Alan Mackenzie]

Kevin Rodgers <ihs_4664@yahoo.com> wrote on Mon, 25 Oct 2004 15:28:14 -0600:
> Alan Mackenzie wrote:
>  > Try C-h f car and C-h f cdr.  What you get on the screen are

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

>  > and

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

>  > Now, to my way of thinking, if I type "C-h f car" it's because I want to
>  > know what the car function does.  The existing doc string seems
>  > implicitly to append "..., and if you're too stupid to know what the car
>  > of a list means, and you're too lazy to spend hours searching through the
>  > available documentation, we don't give a damn."  It's bad enough getting
>  > this sort of "help" from proprietary software, but from Emacs ....???

>  > I suggest these doc-strings be amended to:

>  > "Return the first element of LIST.  If arg is nil, return nil. ....."

>  > and

>  > "The result of removing the first element from LIST, or nil if arg is 
>  > nil.
>  >  Error if arg .....".

> cdr does not remove any elements from LIST.  CLtL says "the rest of the
> list, which is a list with all elements but the first".

> Perhaps the doc string should explicitly destructure the LIST argument:
> "Error if LIST is neither nil nor a (CAR . CDR) cons cell."

I don't think so.  Somebody typing C-h f cdr in earnest is going to be a
raw beginner at lisp.  Although dotted pairs are not rare in Emacs, I
think a list is a more natural concept.  (a b c d) is certainly the same
as (a . (b . (c . (d)))) but I don't think fledgling lisp hackers would
find it helpful to have to deal with this identity.

How about the following for cdr's doc-string:

"Returns the LIST without it's first element.  If arg is nil, return nil.
 Error if arg ...."

? 

> Kevin Rodgers

-- 
Alan Mackenzie (Munich, Germany)
Email: aacm@muuc.dee; to decode, wherever there is a repeated letter
(like "aa"), remove half of them (leaving, say, "a").