From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Re: The doc-strings for car and cdr are insulting. Date: Wed, 27 Oct 2004 18:35:43 -0500 (CDT) Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Message-ID: <200410272335.i9RNZh518737@raven.dms.auburn.edu> References: NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1098920177 15219 80.91.229.6 (27 Oct 2004 23:36:17 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 27 Oct 2004 23:36:17 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Oct 28 01:36:03 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 1CMxKk-0003wE-00 for ; Thu, 28 Oct 2004 01:36:03 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CMxSW-0001l0-MM for ged-emacs-devel@m.gmane.org; Wed, 27 Oct 2004 19:44:04 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CMxSQ-0001kv-7P for emacs-devel@gnu.org; Wed, 27 Oct 2004 19:43:58 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CMxSP-0001kj-Nq for emacs-devel@gnu.org; Wed, 27 Oct 2004 19:43:57 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CMxSP-0001kg-Kj for emacs-devel@gnu.org; Wed, 27 Oct 2004 19:43:57 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CMxKV-0008Gd-M0 for emacs-devel@gnu.org; Wed, 27 Oct 2004 19:35:47 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id i9RNZkFu013829; Wed, 27 Oct 2004 18:35:46 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.7p1+Sun/8.11.7) id i9RNZh518737; Wed, 27 Oct 2004 18:35:43 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: acm@muc.de In-reply-to: (message from Alan Mackenzie on Wed, 27 Oct 2004 18:56:22 +0000 (GMT)) 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: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:29086 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:29086 Alan Mackenzie wrote: I was thinking that, although my proposed doc-strings are not the whole truth, they might be the clearest explanation for a raw beginner at lisp. I do not exactly believe that reading docstrings is the best way for a raw beginner at Lisp to start to learn Elisp. Depending on the person's inclination, he might either use the "Introduction to Programming in Emacs Lisp" manual or the Elisp reference manual. Both are now included with the Emacs distribution. I do not believe that it makes a lot of sense to try to make docstrings play a role that they quite simply can not play. Docstrings for commands should contain notes about interactive usage that are understandable by non-Elisp programmers, because they can be consulted by Emacs users, but that is a different question. I believe that it is perfectly all right for docstrings to assume a certain minimum familiarity with Elisp, except for the description of interactive usage of commands. However, the current (vacuous) definitions They are not vacuous. The _functions_ c[ad]r return the _objects_ c[ad]r, which is not the same thing. It may be easy to guess the purpose of the functions from the name, but it is not bad to make it unambiguously clear anyway. The reason somebody would do `C-h f c[ad]r' is for the (non-trivial) details in the remainder of the docstring, not to get a first introduction to Elisp. How about something like the following, changing "LIST" to "CONS", That might indeed avoid some confusion (namely that the argument would have to be a proper list). Of course, the actual argument in the code would need to be changed too, for consistency. Return the \"left hand side\" of CONS. Your raw beginner would probably not know what a CONS is to begin with. I believe that the current version: "Return the car of list." is shorter and clearer. Sincerely, Luc.