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

[David Kastrup <dak@gnu.org>]

Alan Mackenzie <acm@muc.de> writes:

> I'm assuming that you (RMS) won't mind me posting this to emacs-devel,
> since it's not essentially a personal email.]
>
>>    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 don't reject the idea of making these doc strings clearer; however,
>>this is not the right way present the concepts.
>
> I was thinking that, although my proposed doc-strings are not the
> whole truth, they might be the clearest explanation for a raw
> beginner at lisp.

No.  No no no.  A cons cell is _the_ fundamental data structure of
Lisp.  We must not start waffling around that: this would only confuse
people that have made themselves familiar with the terminology.

And "the result of removing the first element from list" is completely
wrong anyway since no element is removed: the list stays intact.

The main sentence _has_ to be

Return the car/cdr of CONS, or nil if CONS is nil.

You can then add below:

It is an error if CONS is neither a cons cell nor nil.  If CONS
represents an ordinary list, {`car' will return its first
element,`cdr' will return the list without its first element}.

Something like that.

> How about something like the following, changing "LIST" to "CONS", and
> using "lhs" and "rhs":
>
> "car is a built-in function.
>  (car CONS)
>
>  Return the \"left hand side\" of CONS.  If CONS is nil, return nil.
>  If CONS is a list, the car is its first element.
>  Error if arg is not nil and not a cons cell.  See also `car-safe'."

It is just confusing to introduce artificial one-shot terms that are
basically meaningless, like "left hand side".  It implies a left/right
symmetry that is not present when used as a list: the "left" side
points to a list member, the "right" side points to a list of its own.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum