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: [PATCH] Turn on more documentation Date: Tue, 15 May 2012 22:19:43 +0200 Message-ID: <87ipfxkxi8.fsf@pobox.com> References: <87ehqxzke9.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1337113201 21990 80.91.229.3 (15 May 2012 20:20:01 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 15 May 2012 20:20:01 +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 Tue May 15 22:20:00 2012 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1SUODu-00083u-EG for guile-devel@m.gmane.org; Tue, 15 May 2012 22:19:58 +0200 Original-Received: from localhost ([::1]:41892 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SUODt-00079n-P8 for guile-devel@m.gmane.org; Tue, 15 May 2012 16:19:57 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:53720) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SUODq-00078q-Rk for guile-devel@gnu.org; Tue, 15 May 2012 16:19:56 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SUODo-0008P5-Sg for guile-devel@gnu.org; Tue, 15 May 2012 16:19:54 -0400 Original-Received: from a-pb-sasl-sd.pobox.com ([74.115.168.62]:34954 helo=sasl.smtp.pobox.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SUODo-0008Oq-Kd; Tue, 15 May 2012 16:19:52 -0400 Original-Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id D3D40A65D; Tue, 15 May 2012 16:19:49 -0400 (EDT) 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=L8JU540GlKNZ Cv021BF1gB+84gk=; b=jLlCXLOEoxGj94zjKplBVO2/5zIoLVNesGV9Qdc5dz1W YzNVltGaRZ0IfVb/wLiyjUep5Tzd+mTc4yTyGSwZom32uyLJq1IEQmCOXXL3bHrg 5jRLjjkubPybHPn01GFyAkpg3jw9EHcfPLWHdnwOLxThsbb0W4gBUN22FPgRPiY= 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=BP0dSj jnXC37Xm4ECbkaRIm7iWGGJVckvjOsarMljwOqvqACePjJ1zonaxJzK5irB3PjwM efyLrOa/ds2w6AWKHUvZTENMnV1WL8EwqQQa4UTXtte2s++R0BPfSYaLxx9zOjms zy9nuhWliHe+qzPJUgH6/yw8PMRe9mf0PIHrQ= Original-Received: from a-pb-sasl-sd.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id 40C4CA65C; Tue, 15 May 2012 16:19:49 -0400 (EDT) Original-Received: from badger (unknown [90.164.198.39]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTPSA id A3774A65B; Tue, 15 May 2012 16:19:46 -0400 (EDT) In-Reply-To: <87ehqxzke9.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "Sun, 06 May 2012 12:14:22 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.4 (gnu/linux) X-Pobox-Relay-ID: 50C252CA-9ECB-11E1-B18F-E981AF15ED39-02397024!a-pb-sasl-sd.pobox.com X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-Received-From: 74.115.168.62 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:14447 Archived-At: Howdy, On Sun 06 May 2012 12:14, ludo@gnu.org (Ludovic Court=C3=A8s) writes: > The problem is that the auto-generated =E2=80=9CStandard Library=E2=80=9D= section looks > very poor in comparison to the rest of the manual. So we should really > try hard to write good doc by hands for these, and come up with a handy > structure (instead of one node per module, all under =E2=80=9CStandard > Library=E2=80=9D). I agree. I used to think that auto-generation would work as well or better than .texi files, but I think time has definitely proved me wrong, and the GCS right (http://www.gnu.org/prep/standards/html_node/Doc-Strings-and-Manuals.html). The right thing to do is to rework the "Standard Library" documentation into .texi files. Andy --=20 http://wingolog.org/