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

[Alan Mackenzie]

Hi, Emacs!

On Wed, 27 Oct 2004, Richard Stallman wrote (by personal email to me):

[after I had complained on bug-gnu-emacs that the doc-strings for `car'
and `cdr' were "insulting".  "Vacuous" would have been a more objective
and less contentious term.  Sorry for that.

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.
But I think they might at the same time confuse somebody who's grasping
his way onto the next higher level, somebody who's grappling with the
concepts of cons cells, lists, and so on.

Having to make a short one-line definition is quite a constraint.  ;-)

>car and cdr are primitives that operate at the level of cons cells.
>Not all cons cells are considered part of lists, so defining car and
>cdr as if they only worked on lists would not be correct.

However, the current (vacuous) definitions talk about (c[ad]r _LIST_)  ;-)

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

and

"cdr is a built-in function.
 (cdr CONS)

Return the \"right hand side\" of CONS.  If CONS is nil, return nil.
If CONS is a list, the cdr is the list without its first element.
Error if arg is not nil and not a cons cell.  See also `cdr-safe'."

?

-- 
Alan Mackenzie (Munich, Germany)