From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Thien-Thi Nguyen Newsgroups: gmane.emacs.devel Subject: Re: Documentation for car and cdr Date: 25 Jan 2006 19:38:54 -0500 Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1138236256 30154 80.91.229.2 (26 Jan 2006 00:44:16 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 26 Jan 2006 00:44:16 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 26 01:44:13 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1F1vF9-0002cu-HO for ged-emacs-devel@m.gmane.org; Thu, 26 Jan 2006 01:44:07 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1vHu-0005jC-J1 for ged-emacs-devel@m.gmane.org; Wed, 25 Jan 2006 19:46:58 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1F1vCw-00037q-7Z for emacs-devel@gnu.org; Wed, 25 Jan 2006 19:41:50 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1F1vCu-00036Z-1k for emacs-devel@gnu.org; Wed, 25 Jan 2006 19:41:49 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1vCt-00036L-DX for emacs-devel@gnu.org; Wed, 25 Jan 2006 19:41:47 -0500 Original-Received: from [207.245.121.137] (helo=mail.agora-net.com) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA:32) (Exim 4.52) id 1F1vAN-0003t5-1B for emacs-devel@gnu.org; Wed, 25 Jan 2006 19:39:11 -0500 Original-Received: from ttn by mail.agora-net.com with local (Exim 4.50) id 1F1vA6-00056C-Jf; Wed, 25 Jan 2006 19:38:54 -0500 Original-To: Alan Mackenzie In-Reply-To: Original-Lines: 21 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.4 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: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:49558 Archived-At: Alan Mackenzie writes: > I think that "car returns the car" and "cdr returns the cdr" have > negative value - they irritate without enlightening. the irritation is not inherent in the text of a docstring, and neither is the process of enlightenment (if any). > Again, I disagree. A fledgling Elisp hacker is likely to spend time > reading through existing code. She's likely to expect C-h f to tell her > what the mysterious functions do. how the fledgling hacker handles unfulfilled expectations is probably a nice thing for the fledgling hacker to hack, rather than the docstring. > The OP and I want clarity. Most doc strings are rigorous, clear and > helpful at the same time. Why can't those for car and cdr also be so? it can't be so when someone doesn't let it be so. thi