From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: David Kastrup Newsgroups: gmane.emacs.devel Subject: Re: The doc-strings for car and cdr are insulting. Date: Thu, 28 Oct 2004 12:44:45 +0200 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 1098960315 32607 80.91.229.6 (28 Oct 2004 10:45:15 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 28 Oct 2004 10:45:15 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Oct 28 12:45:10 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 1CN7mH-0003Cp-00 for ; Thu, 28 Oct 2004 12:45:09 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CN7u4-0006sb-TG for ged-emacs-devel@m.gmane.org; Thu, 28 Oct 2004 06:53:12 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CN7tx-0006rq-Ad for emacs-devel@gnu.org; Thu, 28 Oct 2004 06:53:05 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CN7tw-0006re-Qw for emacs-devel@gnu.org; Thu, 28 Oct 2004 06:53:05 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CN7tw-0006rb-NY for emacs-devel@gnu.org; Thu, 28 Oct 2004 06:53:04 -0400 Original-Received: from [199.232.76.164] (helo=fencepost.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CN7lu-00016X-9y for emacs-devel@gnu.org; Thu, 28 Oct 2004 06:44:46 -0400 Original-Received: from localhost ([127.0.0.1] helo=lola.goethe.zz) by fencepost.gnu.org with esmtp (Exim 4.34) id 1CN7lB-0006oK-TD; Thu, 28 Oct 2004 06:44:02 -0400 Original-To: Alan Mackenzie In-Reply-To: (Alan Mackenzie's message of "Wed, 27 Oct 2004 18:56:22 +0000 (GMT)") User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/21.3.50 (gnu/linux) 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:29105 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:29105 Alan Mackenzie writes: > 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. No. No no no. A cons cell is _the_ fundamental data structure of Lisp. We must not start waffling around that: this would only confuse people that have made themselves familiar with the terminology. And "the result of removing the first element from list" is completely wrong anyway since no element is removed: the list stays intact. The main sentence _has_ to be Return the car/cdr of CONS, or nil if CONS is nil. You can then add below: It is an error if CONS is neither a cons cell nor nil. If CONS represents an ordinary list, {`car' will return its first element,`cdr' will return the list without its first element}. Something like that. > 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'." It is just confusing to introduce artificial one-shot terms that are basically meaningless, like "left hand side". It implies a left/right symmetry that is not present when used as a list: the "left" side points to a list member, the "right" side points to a list of its own. -- David Kastrup, Kriemhildstr. 15, 44793 Bochum