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

[Chris Smith <smitty_one_each@bigfoot.com>]

Kevin Rodgers <ihs_4664@yahoo.com> writes:

> Richard Stallman wrote:
>  >     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'."
>  >
>  > These are good.
> 
> They are awful.  A cons cells does not have left and right sides any
> more than a list has left and right elements.  A cons cell has car and
> cdr components, which are the first element and the remaining elements
> of a list.
> 
> As Albert Einstein said: Things should be made as simple as possible,
> but no simpler.
> 
> -- 
> Kevin Rodgers

Sir,
 There is a subjective character to documentation.  I have no problem
 with either version.  Possibly corresponding C code could be
 inserted for pedantic purposes.  That, too, would help.
Best,
Chris