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: The doc-strings for car and cdr are insulting. Date: Mon, 25 Oct 2004 17:33:04 +0000 (GMT) Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Message-ID: NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1098725502 1005 80.91.229.6 (25 Oct 2004 17:31:42 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 25 Oct 2004 17:31:42 +0000 (UTC) Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Oct 25 19:31:35 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 1CM8gw-0002XI-00 for ; Mon, 25 Oct 2004 19:31:34 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CM8oa-0004CT-OF for geb-bug-gnu-emacs@m.gmane.org; Mon, 25 Oct 2004 13:39:28 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CM8oG-00044s-E0 for bug-gnu-emacs@gnu.org; Mon, 25 Oct 2004 13:39:08 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CM8oF-00044D-47 for bug-gnu-emacs@gnu.org; Mon, 25 Oct 2004 13:39:07 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CM8oE-000447-Vi for bug-gnu-emacs@gnu.org; Mon, 25 Oct 2004 13:39:07 -0400 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CM8gI-00074u-47 for bug-gnu-emacs@gnu.org; Mon, 25 Oct 2004 13:30:55 -0400 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id RAA00639 for ; Mon, 25 Oct 2004 17:33:05 GMT X-Sender: root@acm.acm Original-To: bug-gnu-emacs@gnu.org 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:9443 X-Report-Spam: http://spam.gmane.org/gmane.emacs.bugs:9443 Hi, Emacs! Emacs 21.3. 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 .....". I haven't scanned through the primitives looking for similar doc-strings. There might well be more. -- Alan Mackenzie (Munich, Germany)