From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: 42toes@gmail.com Newsgroups: gmane.lisp.guile.bugs Subject: bug#9973: Inconsistent documentation of repeated arguments Date: Sun, 06 Nov 2011 14:10:46 -0500 Message-ID: <87obwpawy1.fsf@goof.bjgalaxy> Reply-To: b3timmons@speedymail.org NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: dough.gmane.org 1320676481 28707 80.91.229.12 (7 Nov 2011 14:34:41 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 7 Nov 2011 14:34:41 +0000 (UTC) To: 9973@debbugs.gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Mon Nov 07 15:34:30 2011 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RNQHO-00077L-5A for guile-bugs@m.gmane.org; Mon, 07 Nov 2011 15:34:30 +0100 Original-Received: from localhost ([::1]:48187 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RNQHN-0002Yk-M5 for guile-bugs@m.gmane.org; Mon, 07 Nov 2011 09:34:29 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:46251) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RN8JI-0005Z1-Ki for bug-guile@gnu.org; Sun, 06 Nov 2011 14:23:17 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RN8JH-0000pt-Jl for bug-guile@gnu.org; Sun, 06 Nov 2011 14:23:16 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:34983) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RN8JH-0000pl-EY for bug-guile@gnu.org; Sun, 06 Nov 2011 14:23:15 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RN8Ly-0005LO-CW for bug-guile@gnu.org; Sun, 06 Nov 2011 14:26:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: 42toes@gmail.com Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-guile@gnu.org Resent-Date: Sun, 06 Nov 2011 19:26:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 9973 X-GNU-PR-Package: guile X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-guile@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.132060752420497 (code B ref -1); Sun, 06 Nov 2011 19:26:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 6 Nov 2011 19:25:24 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RN8LL-0005KX-Ia for submit@debbugs.gnu.org; Sun, 06 Nov 2011 14:25:24 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from <42toes@gmail.com>) id 1RN8A3-00054W-IB for submit@debbugs.gnu.org; Sun, 06 Nov 2011 14:13:44 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RN87L-0007Gi-84 for submit@debbugs.gnu.org; Sun, 06 Nov 2011 14:10:56 -0500 Original-Received: from lists.gnu.org ([140.186.70.17]:57453) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RN87L-0007Ge-10 for submit@debbugs.gnu.org; Sun, 06 Nov 2011 14:10:55 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:46402) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RN87J-00007S-UQ for bug-guile@gnu.org; Sun, 06 Nov 2011 14:10:54 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RN87J-0007GQ-3U for bug-guile@gnu.org; Sun, 06 Nov 2011 14:10:53 -0500 Original-Received: from mail-vw0-f41.google.com ([209.85.212.41]:35574) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1RN87I-0007GL-Uj for bug-guile@gnu.org; Sun, 06 Nov 2011 14:10:53 -0500 Original-Received: by vws16 with SMTP id 16so364847vws.0 for ; Sun, 06 Nov 2011 11:10:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=from:to:subject:reply-to:date:message-id:user-agent:mime-version :content-type; bh=d4kjcji4d8kbepd7Y3SKA6BXYmQ5mSJnc0ChuifRqoc=; b=Ca1mZAvSe5LcEAl18iyOhm9xpHtjASi1ulurzDSQ8y47OUpaiahnROE1TyB2rroAJH TitYK76xcx2DjPDtPIcSJ7aYt7IFOI2pbdYd0mPJ5wQVHMEbi7T0Dn55eEfpsBYPuWH9 lfMMHGkHVZpvwoD6sE9GejbjdO+ZvPRtFsBRk= Original-Received: by 10.52.34.100 with SMTP id y4mr23517524vdi.66.1320606652391; Sun, 06 Nov 2011 11:10:52 -0800 (PST) Original-Received: from goof.bjgalaxy (dialup-4.248.40.113.Dial1.Washington2.Level3.net. [4.248.40.113]) by mx.google.com with ESMTPS id ha1sm25789400vdb.17.2011.11.06.11.10.50 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 06 Nov 2011 11:10:51 -0800 (PST) Original-Received: from b3po by goof.bjgalaxy with local (Exim 4.76) (envelope-from <42toes@gmail.com>) id 1RN87C-0005UW-IH for bug-guile@gnu.org; Sun, 06 Nov 2011 14:10:46 -0500 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.91 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Mailman-Approved-At: Sun, 06 Nov 2011 14:25:21 -0500 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sun, 06 Nov 2011 14:26:02 -0500 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-Mailman-Approved-At: Mon, 07 Nov 2011 09:34:23 -0500 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:5903 Archived-At: Before making some changes to the docs, I just wanted to give a heads up. Recall the motivation behind Scheme "It was designed to have an exceptionally clear and simple semantics and few different ways to form expressions." Why not tighten up notation in the docs as well as in the language? My hunch is that in the long run doing so will help those learning Guile. Examples from the current Guile Reference: (1) -- Scheme Procedure: string-append . args (2) -- Scheme Procedure: append lst1 ... lstN (3) -- Scheme Procedure: error msg args ... (4) -- Scheme Procedure: error who message irritant1 ... IMO, (4) is the right thing. In software documentation '...' means 'repeated zero or more times', so 'arg ...' always includes 'args' as a possibility, rendering 'args ...' redundant and potentially confusing. Of course, in principle, we might intend 'args' to mean an aggregate data structure such as list, but in that case 'arglist', 'list', etc. would be clearer IMO. Thus, I would fix (1-3) to be (1) -- Scheme Procedure: string-append arg ... (2) -- Scheme Procedure: append lst ... obj (3) -- Scheme Procedure: error msg arg ... (The 'obj' from (2) is particular to 'append'.) FWIW, highly regarded docs such as the RnRS reports, _The Scheme Programming Language_ by Dybvig, CLtL2, etc. are consistent on such things. Something like 'elem1 ... elemN' might be useful in a discussion of say the Ith element and so on, but it not easy enough just to use 'elem ...' in the definition header and then elaborate in the definition body w/ 'elem1 ... elemN', etc.? Thanks, Bake