Re: Documentation for car and cdr

[Alan Mackenzie]

On Wed, 25 Jan 2006, David Kastrup wrote:

>Mario Domenech Goulart <address@hidden> writes:

>> Hello,

>> Currently, the documentation for cdr is:

>> ,----[ M-x describe-function <RET> cdr <RET> ]
>> | cdr is a built-in function in `C source code'.
>> | (cdr list)
>> | 
>> | 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'.
>> `----

[ snip the same for car. ]

>> Saying "car returns the car" and "cdr returns the cdr" doesn't sound
>> very useful for me if I would like to know what car and cdr do, unless
>> I knew what "car" and "cdr" mean (then I wouldn't check the
>> documentation). :-)

>> Wouldn't it be better to write something like "Return the first
>> element of list" and "Return a list containing all but the first
>> element of list" for car and cdr, respectively?

>No.  cons cells don't need to point to an atom in their car, or to a
>cons cell or nil in their cdr.  This is fundamental Lisp terminology.
>It would be ok to add a cross reference to the Elisp manual, but the
>description of the functions is dead-on and should not be replaced by
>some watered-down half-inaccurate stuff.

This description of the function is near useless.  It is pure sophistry to
distinguish between the abstract concept "cdr", and the function "cdr",
as though they were really two different things.  It's the sort of thing
that gets me fuming with rage when I encounter it in proprietary
documentation.

What does this doc-string say to the novice lisp programmer?  It says
"We're telling you that the function called \"cdr\" actually returns the
abstract \"cdr\" of a lisp object, just in case that isn't obvious."  It
goes on, implicitly by omission, to say "if you really don't know what a
cdr is by this stage, you're so stupid that there's no point in us
bothering to tell you."

How many other functions could we describe in this way.  How about
`bobp', for example?  "bobp returns t if bobp is true, otherwise it
returns nil".

I suggest making this doc-string more helpful by appending the following
to it:

"Loosely speaking, the cdr of LIST is LIST without its first element."

, and the other one:

"Loosely speaking, the car of LIST is its first element.".

Each of these sentences is completely accurate (by virtue of "loosely
speaking"), regardless of whether LIST is a list, a dotted pair, or nil.

>David Kastrup, Kriemhildstr. 15, 44793 Bochum

-- 
Alan Mackenzie (Munich, Germany)