From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: Re: The doc-strings for car and cdr are insulting. Date: 26 Oct 2004 21:49:28 +0200 Organization: muc.de e.V. -- private internet access Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Message-ID: References: NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1098820188 10949 80.91.229.6 (26 Oct 2004 19:49:48 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 26 Oct 2004 19:49:48 +0000 (UTC) Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Oct 26 21:49:39 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 1CMXK6-0006Qc-00 for ; Tue, 26 Oct 2004 21:49:39 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CMXRo-0003Gh-Vw for geb-bug-gnu-emacs@m.gmane.org; Tue, 26 Oct 2004 15:57:37 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CMXRl-0003Fa-Cz for bug-gnu-emacs@gnu.org; Tue, 26 Oct 2004 15:57:33 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CMXRk-0003FG-Oq for bug-gnu-emacs@gnu.org; Tue, 26 Oct 2004 15:57:33 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CMXRk-0003F6-L8 for bug-gnu-emacs@gnu.org; Tue, 26 Oct 2004 15:57:32 -0400 Original-Received: from [199.232.76.164] (helo=fencepost.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CMXK1-0006pF-82 for bug-gnu-emacs@gnu.org; Tue, 26 Oct 2004 15:49:33 -0400 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by fencepost.gnu.org with esmtp (Exim 4.34) id 1CMXJU-00048X-Gx for gnu-emacs-bug@ftp.gnu.org; Tue, 26 Oct 2004 15:49:00 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.34) id 1CMXJz-0006ow-SU for gnu-emacs-bug@ftp.gnu.org; Tue, 26 Oct 2004 15:49:32 -0400 Original-Received: from [193.149.48.2] (helo=marvin.muc.de) by monty-python.gnu.org with smtp (Exim 4.34) id 1CMXJz-0006or-BO for gnu-emacs-bug@ftp.gnu.org; Tue, 26 Oct 2004 15:49:31 -0400 Original-Received: (qmail 48207 invoked by uid 8); 26 Oct 2004 19:49:28 -0000 Original-To: gnu-emacs-bug@prep.ai.mit.edu Original-Path: not-for-mail Original-Newsgroups: gnu.emacs.bug Original-Date: Tue, 26 Oct 2004 17:23:05 +0000 Original-Lines: 55 Original-NNTP-Posting-Host: acm.muc.de Original-X-Trace: marvin.muc.de 1098820168 48203 193.149.49.134 (26 Oct 2004 19:49:28 GMT) Original-X-Complaints-To: news-admin@muc.de Original-NNTP-Posting-Date: 26 Oct 2004 19:49:28 GMT User-Agent: tin/1.4.5-20010409 ("One More Nightmare") (UNIX) (Linux/2.0.35 (i686)) X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: main.gmane.org gmane.emacs.bugs:9459 X-Report-Spam: http://spam.gmane.org/gmane.emacs.bugs:9459 Kevin Rodgers wrote on Mon, 25 Oct 2004 15:28:14 -0600: > Alan Mackenzie wrote: > > Try C-h f car and C-h f cdr. What you get on the screen are > > "Return the car of LIST. If arg is nil, return nil. > > Error if arg is not nil and not a cons cell. See also `car-safe'." > > and > > "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'." > > Now, to my way of thinking, if I type "C-h f car" it's because I want to > > know what the car function does. The existing doc string seems > > implicitly to append "..., and if you're too stupid to know what the car > > of a list means, and you're too lazy to spend hours searching through the > > available documentation, we don't give a damn." It's bad enough getting > > this sort of "help" from proprietary software, but from Emacs ....??? > > 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 .....". > cdr does not remove any elements from LIST. CLtL says "the rest of the > list, which is a list with all elements but the first". > Perhaps the doc string should explicitly destructure the LIST argument: > "Error if LIST is neither nil nor a (CAR . CDR) cons cell." I don't think so. Somebody typing C-h f cdr in earnest is going to be a raw beginner at lisp. Although dotted pairs are not rare in Emacs, I think a list is a more natural concept. (a b c d) is certainly the same as (a . (b . (c . (d)))) but I don't think fledgling lisp hackers would find it helpful to have to deal with this identity. How about the following for cdr's doc-string: "Returns the LIST without it's first element. If arg is nil, return nil. Error if arg ...." ? > Kevin Rodgers -- Alan Mackenzie (Munich, Germany) Email: aacm@muuc.dee; to decode, wherever there is a repeated letter (like "aa"), remove half of them (leaving, say, "a").