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

[Kevin Rodgers]

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

--
Kevin Rodgers