The doc-strings for car and cdr are insulting.

The doc-strings for car and cdr are insulting.

[Alan Mackenzie]

Hi, Emacs!

Emacs 21.3.

Try C-h f car and C-h f cdr.  What you get on the screen are

"Return the car of LIST.  If arg is nil, return nil.
 Error if arg is not nil and not a cons cell.  See also `car-safe'."

and

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

Now, to my way of thinking, if I type "C-h f car" it's because I want to
know what the car function does.  The existing doc string seems
implicitly to append "..., and if you're too stupid to know what the car
of a list means, and you're too lazy to spend hours searching through the
available documentation, we don't give a damn."  It's bad enough getting
this sort of "help" from proprietary software, but from Emacs ....???

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 haven't scanned through the primitives looking for similar doc-strings.
There might well be more.

-- 
Alan Mackenzie (Munich, Germany)

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

[Kevin Rodgers]

Alan Mackenzie wrote:
 > Try C-h f car and C-h f cdr.  What you get on the screen are
 >
 > "Return the car of LIST.  If arg is nil, return nil.
 >  Error if arg is not nil and not a cons cell.  See also `car-safe'."
 >
 > and
 >
 > "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'."
 >
 > Now, to my way of thinking, if I type "C-h f car" it's because I want to
 > know what the car function does.  The existing doc string seems
 > implicitly to append "..., and if you're too stupid to know what the car
 > of a list means, and you're too lazy to spend hours searching through the
 > available documentation, we don't give a damn."  It's bad enough getting
 > this sort of "help" from proprietary software, but from Emacs ....???
 >
 > 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 .....".

cdr does not remove any elements from LIST.  CLtL says "the rest of the
list, which is a list with all elements but the first".

Perhaps the doc string should explicitly destructure the LIST argument:
"Error if LIST is neither nil nor a (CAR . CDR) cons cell."

-- 
Kevin Rodgers

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

[Alan Mackenzie]

Kevin Rodgers <ihs_4664@yahoo.com> wrote on Mon, 25 Oct 2004 15:28:14 -0600:
> Alan Mackenzie wrote:
>  > Try C-h f car and C-h f cdr.  What you get on the screen are

>  > "Return the car of LIST.  If arg is nil, return nil.
>  >  Error if arg is not nil and not a cons cell.  See also `car-safe'."

>  > and

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

>  > Now, to my way of thinking, if I type "C-h f car" it's because I want to
>  > know what the car function does.  The existing doc string seems
>  > implicitly to append "..., and if you're too stupid to know what the car
>  > of a list means, and you're too lazy to spend hours searching through the
>  > available documentation, we don't give a damn."  It's bad enough getting
>  > this sort of "help" from proprietary software, but from Emacs ....???

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

> cdr does not remove any elements from LIST.  CLtL says "the rest of the
> list, which is a list with all elements but the first".

> Perhaps the doc string should explicitly destructure the LIST argument:
> "Error if LIST is neither nil nor a (CAR . CDR) cons cell."

I don't think so.  Somebody typing C-h f cdr in earnest is going to be a
raw beginner at lisp.  Although dotted pairs are not rare in Emacs, I
think a list is a more natural concept.  (a b c d) is certainly the same
as (a . (b . (c . (d)))) but I don't think fledgling lisp hackers would
find it helpful to have to deal with this identity.

How about the following for cdr's doc-string:

"Returns the LIST without it's first element.  If arg is nil, return nil.
 Error if arg ...."

? 

> Kevin Rodgers

-- 
Alan Mackenzie (Munich, Germany)
Email: aacm@muuc.dee; to decode, wherever there is a repeated letter
(like "aa"), remove half of them (leaving, say, "a").

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)

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

[Luc Teirlinck]

Alan Mackenzie wrote:

   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.

I do not exactly believe that reading docstrings is the best way for a
raw beginner at Lisp to start to learn Elisp.  Depending on the
person's inclination, he might either use the "Introduction to
Programming in Emacs Lisp" manual or the Elisp reference manual.  Both
are now included with the Emacs distribution.  I do not believe that
it makes a lot of sense to try to make docstrings play a role that
they quite simply can not play.

Docstrings for commands should contain notes about interactive usage
that are understandable by non-Elisp programmers, because they can be
consulted by Emacs users, but that is a different question.

I believe that it is perfectly all right for docstrings to assume a
certain minimum familiarity with Elisp, except for the description of
interactive usage of commands.

   However, the current (vacuous) definitions

They are not vacuous.  The _functions_ c[ad]r return the _objects_
c[ad]r, which is not the same thing.  It may be easy to guess the
purpose of the functions from the name, but it is not bad to make it
unambiguously clear anyway.  The reason somebody would do `C-h f
c[ad]r' is for the (non-trivial) details in the remainder of the
docstring, not to get a first introduction to Elisp.

   How about something like the following, changing "LIST" to "CONS",

That might indeed avoid some confusion (namely that the argument would
have to be a proper list).  Of course, the actual argument in the code
would need to be changed too, for consistency.

   Return the \"left hand side\" of CONS.

Your raw beginner would probably not know what a CONS is to begin
with.   I believe that the current version:  "Return the car of list."
is shorter and clearer.

Sincerely,

Luc.

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

[Luc Teirlinck]

>From my prior message:

   I believe that the current version:  "Return the car of list."
   is shorter and clearer.

Although "Return the car of CONS." might indeed possibly avoid some
confusion.

Sincerely,

Luc.

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

[David Kastrup]

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

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

[Richard Stallman]

    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.

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

[Lennart Borgman]

----- Original Message ----- 
From: "Richard Stallman" <rms@gnu.org>
To: "Alan Mackenzie" <acm@muc.de>


:     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.

As someone who just recently learned elisp I have to agree. Much better than
the old version. It was just by chance I happened to find out about CONS.
(Like most "users" I only read the manual when I have too ;-) This will be a
quicker road to learn.

Actually I would like some links saying for more info see the Elisp Info
pages, pointing to some relevant page there. (But I guess that is not
something for now.)

- Lennart

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

[Kevin Rodgers]

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

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

[Chris Smith]

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