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:35:32 +0000 (GMT) Message-ID: References: <200601252211.k0PMB3618664@raven.dms.auburn.edu> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1138283104 14969 80.91.229.2 (26 Jan 2006 13:45:04 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 26 Jan 2006 13:45:04 +0000 (UTC) Cc: mario.goulart@gmail.com, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 26 14:44:56 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 1F27Qb-0007RL-Ks for ged-emacs-devel@m.gmane.org; Thu, 26 Jan 2006 14:44:46 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F26Mu-0003E3-Od for ged-emacs-devel@m.gmane.org; Thu, 26 Jan 2006 07:36:53 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1F25aP-0005uz-Bc for emacs-devel@gnu.org; Thu, 26 Jan 2006 06:46:46 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1F25YW-0005gY-Bi for emacs-devel@gnu.org; Thu, 26 Jan 2006 06:45:17 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F25TH-0004gG-EQ for emacs-devel@gnu.org; Thu, 26 Jan 2006 06:39:24 -0500 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.52) id 1F25Qk-0005RN-GR; Thu, 26 Jan 2006 06:36:47 -0500 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id WAA03411; Wed, 25 Jan 2006 22:35:34 GMT X-Sender: root@acm.acm Original-To: Luc Teirlinck In-Reply-To: <200601252211.k0PMB3618664@raven.dms.auburn.edu> 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:49577 Archived-At: On Wed, 25 Jan 2006, Luc Teirlinck wrote: >Describing basic concepts like car, cdr, cons cell, list and so on is >the task of manuals, not of docstrings. That has not been established. And even if it had, a one-liner description in a doc-string is likely to be convenient and helpful. >If somebody is not familiar with the basic concepts, they have to read a >manual, where those concepts can be put into the proper context, _not_ >individual docstrings. Suppose somebody has read the manuals, a bit. She knows what car and cdr mean, roughly, but isn't quite sure which is which. C-h f is a convenient way of checking. Or it could be. >There are two different Elisp manuals included with the Emacs >distribution. Why on earth would a beginning Elisp programmer try to >learn Elisp exclusively through the docstrings rather than through the >one of these two manuals? Your begging the question here. I don't think anybody (least of all me) is suggesting that doc-strings should supplant the manuals. But I am saying that somebody needing a short snappy one-liner description of a function shouldn't be forced to go through the drudgery of opening the Elisp manual, finding the page "cdr" is on, then ploughing through all the "broadening your horizons" documentation to reach that one critical sentence. Different people use manuals and doc-strings in different ways. >Sincerely, >Luc. -- Alan.