The doc-strings for car and cdr are insulting.

[Alan Mackenzie]

Hi, Emacs!

Emacs 21.3.

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

I haven't scanned through the primitives looking for similar doc-strings.
There might well be more.

-- 
Alan Mackenzie (Munich, Germany)