Re: Documentation for car and cdr

[Alan Mackenzie]

On Wed, 25 Jan 2006, Bill Atkins wrote:

>On 1/25/06, Alan Mackenzie <address@hidden> wrote:


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


>Why do we need to "speak loosely"?

So as to be immediately understandable.

>Including a link to a description of cons cells is completely adequate.

Yes, but only in addition to an intuitively meaningful description, not
instead of it.  Because that would force the poor hacker to go and look
somewhere else.  Having to go and look somewhere else is always a pain in
the posterior, particularly when a one-liner explanation is all that is
sought.

>Your definitions are misleading in any case.  CAR and CDR do not
>necessarily deal with lists;

It is merely that the parameter to cdr is called LIST.  I haven't
otherwise implied that it must be a list.  For example "(a . b)" without
it's first element is "b", or something like it.

>as others have pointed out, a cons is a distinct data structure that is
>used to compose lists only by convention.  These are not "abstract
>concepts," they're simply how Lisp works.

We're reduced to silly semantic arguments about "abstract" now.  Others
have asserted that "cdr returns the cdr" is a coherent description of
cdr.  They are thus implying that "cdr" is semantically different from
"cdr", otherwise that description would be circular and vacuous.  I
disagree with them, and used the term "abstract concept" only to try to
highlight what to me is an absurdity.

>--
>Bill Atkins

-- 
Alan Mackenzie (Munich, Germany)