From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Chris Smith Newsgroups: gmane.emacs.devel Subject: Re: The doc-strings for car and cdr are insulting. Date: 29 Oct 2004 20:21:36 -0400 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 1099137143 30867 80.91.229.6 (30 Oct 2004 11:52:23 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 30 Oct 2004 11:52:23 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Oct 30 13:52:17 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 1CNrmK-0008Hz-00 for ; Sat, 30 Oct 2004 13:52:16 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CNruD-000091-MD for ged-emacs-devel@m.gmane.org; Sat, 30 Oct 2004 08:00:25 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CNrtr-00008l-6O for emacs-devel@gnu.org; Sat, 30 Oct 2004 08:00:03 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CNrtp-00008X-IH for emacs-devel@gnu.org; Sat, 30 Oct 2004 08:00:02 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CNrtp-00008U-DI for emacs-devel@gnu.org; Sat, 30 Oct 2004 08:00:01 -0400 Original-Received: from [80.91.229.2] (helo=main.gmane.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CNrle-0000fR-AT for emacs-devel@gnu.org; Sat, 30 Oct 2004 07:51:34 -0400 Original-Received: from root by main.gmane.org with local (Exim 3.35 #1 (Debian)) id 1CNrlc-0000hd-00 for ; Sat, 30 Oct 2004 13:51:32 +0200 Original-Received: from ip24-255-97-25.dc.dc.cox.net ([24.255.97.25]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sat, 30 Oct 2004 13:51:32 +0200 Original-Received: from smitty_one_each by ip24-255-97-25.dc.dc.cox.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sat, 30 Oct 2004 13:51:32 +0200 X-Injected-Via-Gmane: http://gmane.org/ Original-To: emacs-devel@gnu.org Original-Lines: 42 Original-X-Complaints-To: usenet@sea.gmane.org X-Gmane-NNTP-Posting-Host: ip24-255-97-25.dc.dc.cox.net User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3 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:29166 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:29166 Kevin Rodgers 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