From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: The doc-strings for car and cdr are insulting. Date: Wed, 27 Oct 2004 18:56:22 +0000 (GMT) Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Message-ID: References: NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1098906303 10059 80.91.229.6 (27 Oct 2004 19:45:03 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 27 Oct 2004 19:45:03 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Oct 27 21:44:58 2004 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1CMtj7-0001ke-00 for ; Wed, 27 Oct 2004 21:44:57 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CMtqs-0006bO-V5 for ged-emacs-devel@m.gmane.org; Wed, 27 Oct 2004 15:52:58 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CMtqg-0006XF-P4 for emacs-devel@gnu.org; Wed, 27 Oct 2004 15:52:46 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CMtqf-0006Wl-UK for emacs-devel@gnu.org; Wed, 27 Oct 2004 15:52:46 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CMtqf-0006Wh-S0 for emacs-devel@gnu.org; Wed, 27 Oct 2004 15:52:45 -0400 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CMtio-0003dB-Ft for emacs-devel@gnu.org; Wed, 27 Oct 2004 15:44:39 -0400 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id SAA00622 for ; Wed, 27 Oct 2004 18:56:24 GMT X-Sender: root@acm.acm Original-To: emacs-devel@gnu.org In-Reply-To: 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: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:29075 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:29075 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)