From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Andy Wingo Newsgroups: gmane.lisp.guile.devel Subject: Re: rfc: (ice-9 accumulate) Date: Mon, 11 Jan 2010 21:57:14 +0100 Message-ID: References: <873a2fo8wc.fsf@ambire.localdomain> <8763799nwr.fsf@ambire.localdomain> <87eilweq0k.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1263243449 2297 80.91.229.12 (11 Jan 2010 20:57:29 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 11 Jan 2010 20:57:29 +0000 (UTC) Cc: guile-devel@gnu.org To: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Mon Jan 11 21:57:21 2010 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1NURK6-0006PA-2D for guile-devel@m.gmane.org; Mon, 11 Jan 2010 21:57:14 +0100 Original-Received: from localhost ([127.0.0.1]:35122 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NURK6-0001X6-QA for guile-devel@m.gmane.org; Mon, 11 Jan 2010 15:57:14 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NURJS-0001FQ-30 for guile-devel@gnu.org; Mon, 11 Jan 2010 15:56:34 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NURJL-00017f-Hu for guile-devel@gnu.org; Mon, 11 Jan 2010 15:56:31 -0500 Original-Received: from [199.232.76.173] (port=55862 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NURJK-00017H-3l for guile-devel@gnu.org; Mon, 11 Jan 2010 15:56:26 -0500 Original-Received: from a-pb-sasl-quonix.pobox.com ([208.72.237.25]:32941 helo=sasl.smtp.pobox.com) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NURJF-0005i4-4I; Mon, 11 Jan 2010 15:56:21 -0500 Original-Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id 4E20C90BFC; Mon, 11 Jan 2010 15:56:20 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; s=sasl; bh=8W4/CheQf2iF 9dG5I/iX55UppT0=; b=sExgI4WpDKfJyINUX4tu+LfaeZ/uhyEq6pFT6PpjC/Rh 7JGkpOYm1H0jhiAo/1NG4kwpNWtjC/Lxjq7WANr1h5rL57W0OXM7J4P+CwNI3odk KPgPke2f+fSrA63/fdnBHh0q1N7W0zEkWrZqGaEulpFA/p1YyshoiMSG6hVYSm8= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type:content-transfer-encoding; q=dns; s=sasl; b=rNurJC wQXhlEqakiyiKq8baSPNJFyJOkxRPqO0kILm/SSoMXoy1ihKWTvneBOt91RbkwsU JN/zbAJ1vmHzrJ8S71rI/oZ+P/rFmZJC6UWi/8wFWqO2IGCsuJq5U5WgrhOO4L0C 82i3FJ4CmjDpKagSEorDCQb3JFpV4X2h4WXTI= Original-Received: from a-pb-sasl-quonix. (unknown [127.0.0.1]) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id 357A390BFA; Mon, 11 Jan 2010 15:56:19 -0500 (EST) Original-Received: from unquote (unknown [81.38.180.33]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTPSA id 3C78B90BF8; Mon, 11 Jan 2010 15:56:16 -0500 (EST) In-Reply-To: <87eilweq0k.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "Mon, 11 Jan 2010 14:21:15 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.92 (gnu/linux) X-Pobox-Relay-ID: C44F988A-FEF3-11DE-BC46-9D59EE7EF46B-02397024!a-pb-sasl-quonix.pobox.com X-detected-operating-system: by monty-python.gnu.org: Solaris 10 (beta) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:9860 Archived-At: On Mon 11 Jan 2010 14:21, ludo@gnu.org (Ludovic Court=C3=A8s) writes: > Hello, > > Thien-Thi Nguyen writes: > >> There's lots of stuff in ice-9 that noone knows about, but I don't >> think there's something like this. Hopefully we can document more of >> it using the new (texinfo reflection) infrastructure. >> >> In reply to a similar comment from Ludovic, i offered to submit patches >> for missing (ice-9 foo) documentation. I hereby revise that offer to >> submit patches using this infrastructure, once i get around to playing >> with it. I imagine it can't be much different from Guile 1.4.x's. > > I=E2=80=99d prefer if it were used only for non-ice-9 modules. I really > sympathize with what the GCS says (info "(standards) Doc Strings and > Manuals"): > > Some programming systems, such as Emacs, provide a documentation > string for each function, command or variable. You may be tempted to > write a reference manual by compiling the documentation strings and > writing a little additional text to go around them--but you must not > do it. That approach is a fundamental mistake. The text of > well-written documentation strings will be entirely wrong for a > manual. I agree with this, largely; but of course texi documentation has the disadvantage that it can (and does) grow out-of-sync with source. For small modules, a nicely written commentary plus an expository (i.e., in-order) layout of exported procedures, along with their docstrings, can get you 80% of the way there, very easily. And at least that way you know it's accurate. Also we could hack up other in-source documentary mechanisms that approach manual-style documentation more closely. For example a Manual block, like we now have Commentary. Andy --=20 http://wingolog.org/