Re: Documentation for car and cdr

[Bill Atkins]

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)
>
>
>
>
> _______________________________________________
> Emacs-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/emacs-devel
>

Why do we need to "speak loosely"?  Including a link to a description
of cons cells is completely adequate.

Your definitions are misleading in any case.  CAR and CDR do not
necessarily deal with lists; 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.

--
Bill Atkins