The doc-strings for car and cdr are insulting.

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)

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

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