From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Documentation for car and cdr Date: Wed, 25 Jan 2006 21:41:26 +0000 (GMT) Message-ID: References: <66b7e34b0601251343i254e84c3o4b1bd882f01e2935@mail.gmail.com> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1138230221 10245 80.91.229.2 (25 Jan 2006 23:03:41 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 25 Jan 2006 23:03:41 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 26 00:03:38 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1F1tfd-0000yi-B6 for ged-emacs-devel@m.gmane.org; Thu, 26 Jan 2006 00:03:21 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1tiO-0001CN-Jn for ged-emacs-devel@m.gmane.org; Wed, 25 Jan 2006 18:06:12 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1F1ti4-00018i-3T for emacs-devel@gnu.org; Wed, 25 Jan 2006 18:05:52 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1F1ti3-000172-D2 for emacs-devel@gnu.org; Wed, 25 Jan 2006 18:05:51 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1ti2-00016f-Fj for emacs-devel@gnu.org; Wed, 25 Jan 2006 18:05:50 -0500 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.52) id 1F1tfU-0004M4-1B for emacs-devel@gnu.org; Wed, 25 Jan 2006 18:03:13 -0500 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id VAA03339; Wed, 25 Jan 2006 21:41:28 GMT X-Sender: root@acm.acm Original-To: Bill Atkins In-Reply-To: <66b7e34b0601251343i254e84c3o4b1bd882f01e2935@mail.gmail.com> X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:49544 Archived-At: On Wed, 25 Jan 2006, Bill Atkins wrote: >On 1/25/06, Alan Mackenzie wrote: >> On Wed, 25 Jan 2006, David Kastrup wrote: >> >Mario Domenech Goulart writes: >> >> Hello, >> >> Currently, the documentation for cdr is: >> >> ,----[ M-x describe-function cdr ] >> >> | 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) >Why do we need to "speak loosely"? So as to be immediately understandable. >Including a link to a description of cons cells is completely adequate. Yes, but only in addition to an intuitively meaningful description, not instead of it. Because that would force the poor hacker to go and look somewhere else. Having to go and look somewhere else is always a pain in the posterior, particularly when a one-liner explanation is all that is sought. >Your definitions are misleading in any case. CAR and CDR do not >necessarily deal with lists; It is merely that the parameter to cdr is called LIST. I haven't otherwise implied that it must be a list. For example "(a . b)" without it's first element is "b", or something like it. >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. We're reduced to silly semantic arguments about "abstract" now. Others have asserted that "cdr returns the cdr" is a coherent description of cdr. They are thus implying that "cdr" is semantically different from "cdr", otherwise that description would be circular and vacuous. I disagree with them, and used the term "abstract concept" only to try to highlight what to me is an absurdity. >-- >Bill Atkins -- Alan Mackenzie (Munich, Germany)