From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Documentation for car and cdr Date: Wed, 25 Jan 2006 22:16:10 +0000 (GMT) Message-ID: References: Reply-To: Alan Mackenzie NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1138230451 11103 80.91.229.2 (25 Jan 2006 23:07:31 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 25 Jan 2006 23:07:31 +0000 (UTC) Cc: Mario Domenech Goulart , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 26 00:07:29 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 1F1tjK-0001zk-P2 for ged-emacs-devel@m.gmane.org; Thu, 26 Jan 2006 00:07:11 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1tj9-0001fB-PI for ged-emacs-devel@m.gmane.org; Wed, 25 Jan 2006 18:06:59 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1F1ti9-0001F2-UH for emacs-devel@gnu.org; Wed, 25 Jan 2006 18:05:58 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1F1ti9-0001EH-AF for emacs-devel@gnu.org; Wed, 25 Jan 2006 18:05:57 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F1ti9-0001E2-3s for emacs-devel@gnu.org; Wed, 25 Jan 2006 18:05:57 -0500 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.52) id 1F1tfX-0004M4-6C; Wed, 25 Jan 2006 18:03:16 -0500 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id WAA03345; Wed, 25 Jan 2006 22:16:12 GMT X-Sender: root@acm.acm Original-To: Thien-Thi Nguyen In-Reply-To: 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:49545 Archived-At: Hi, Thi! On 25 Jan 2006, Thien-Thi Nguyen wrote: >Alan Mackenzie writes: >> Each of these sentences is completely accurate (by virtue of "loosely >> speaking"), regardless of whether LIST is a list, a dotted pair, or >> nil. >blech. placing "loosely speaking" in the docstring decreases >credibility (take it from a practiced word weasler: those are weasel >words), and does not clarify anything. that's certainly a bad move. How would you answer "What's Emacs?". "Loosely speaking, it's a programmers' editor" is correct, and a good answer. "A programmers' editor" will raise the hackles of Gnus fans and some professional writers. "An extensible editing system, programmed in lisp, including specialized facilities for ..... [ snip next 10 line ]" will bore the questioner to tears and make him wish he hadn't asked. "It's Emacs!" is vacuous. Describing intuitively what car/cdr mean is useful. I think that "car returns the car" and "cdr returns the cdr" have negative value - they irritate without enlightening. >(note: CERTAINLY, not just LOOSELY SPEAKING.) >this whole thread is populated by people who know what CAR and CDR are. >people who don't, who *might* be confused, who *may* be offended by such >crass self-documentation; they won't read this or the docstring anyway! 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. >now, i suppose someone will lark an ostensibly non-expert friend into >sending a bug report on this. what, is it 1-april already? I submitted precisely this issue as a bug a little over a year ago. (And no, I have not communicated with the OP in this thread.) From that discussion, and this one, it seems clear that people have widely varying expectations of what doc-strings should be. David K. wants rigour at all costs; 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? >thi -- Alan.