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 19:54:36 +0000 (GMT) Message-ID: References: <85acdlnrqf.fsf@lola.goethe.zz> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1138224555 20550 80.91.229.2 (25 Jan 2006 21:29:15 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 25 Jan 2006 21:29:15 +0000 (UTC) Cc: Mario Domenech Goulart , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jan 25 22:29:12 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 1F1sCW-0007aF-1B for ged-emacs-devel@m.gmane.org; Wed, 25 Jan 2006 22:29:12 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1sE7-00046b-6U for ged-emacs-devel@m.gmane.org; Wed, 25 Jan 2006 16:30:51 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1F1sC8-00026f-Sl for emacs-devel@gnu.org; Wed, 25 Jan 2006 16:28:49 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1F1sC3-0001y8-Vy for emacs-devel@gnu.org; Wed, 25 Jan 2006 16:28:46 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1sC3-0001wP-3M for emacs-devel@gnu.org; Wed, 25 Jan 2006 16:28:43 -0500 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.52) id 1F1s9I-0003m1-UT; Wed, 25 Jan 2006 16:25:54 -0500 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id TAA02646; Wed, 25 Jan 2006 19:54:38 GMT X-Sender: root@acm.acm Original-To: David Kastrup In-Reply-To: <85acdlnrqf.fsf@lola.goethe.zz> 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:49537 Archived-At: 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)