From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Noah Lavine Newsgroups: gmane.lisp.guile.devel Subject: Re: [PATCH] Turn on more documentation Date: Sat, 12 May 2012 16:56:57 -0400 Message-ID: References: <87ehqxzke9.fsf@gnu.org> <87lil4vz9g.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1336856227 9402 80.91.229.3 (12 May 2012 20:57:07 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 12 May 2012 20:57:07 +0000 (UTC) Cc: guile-devel@gnu.org To: =?ISO-8859-1?Q?Ludovic_Court=E8s?= Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sat May 12 22:57:06 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 1STJNB-0004Uq-Uo for guile-devel@m.gmane.org; Sat, 12 May 2012 22:57:06 +0200 Original-Received: from localhost ([::1]:38433 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1STJNB-0008RV-81 for guile-devel@m.gmane.org; Sat, 12 May 2012 16:57:05 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:38939) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1STJN8-0008RE-67 for guile-devel@gnu.org; Sat, 12 May 2012 16:57:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1STJN6-0006FO-H8 for guile-devel@gnu.org; Sat, 12 May 2012 16:57:01 -0400 Original-Received: from mail-yx0-f169.google.com ([209.85.213.169]:33894) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1STJN6-0006F9-AN; Sat, 12 May 2012 16:57:00 -0400 Original-Received: by yenm7 with SMTP id m7so4336838yen.0 for ; Sat, 12 May 2012 13:56:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=+QFa3gNFwNEJPFSG53bvBFxxjJBxgCY9XyUBm1HwptQ=; b=Rc6m3IQfvdVVhFMTyDg319ZmIKDugNIwCRgNdGOCOl4dvBh2h2srRnFo9YczEgH6yw dxCpUX8HIEfgRxbEB9mKd47qWItIYgl+Zi+vg06OIshO+DRw2X8WHVrCPpfq2eQGVheS BwfDkxB25djjLAifR1/Ynn4kApEBOGhXLlBGzb8xNWgJeqDR8d5YYt9NRfg4M1GsKFn7 6vQrmd0yA+CZWfMJg3gbWGnTWGd0kuRnvelORUF3fzzJjeNlXUy6ugGAXZn0WH9WeBdu gImsvYnLWcpUP1mQdAZrDzLrF5baRnCqY31Ht/3Qor/+ie5SphWakseSERaCJ97NaRme W38A== Original-Received: by 10.50.106.228 with SMTP id gx4mr1433187igb.7.1336856217795; Sat, 12 May 2012 13:56:57 -0700 (PDT) Original-Received: by 10.42.29.200 with HTTP; Sat, 12 May 2012 13:56:57 -0700 (PDT) In-Reply-To: <87lil4vz9g.fsf@gnu.org> X-Google-Sender-Auth: FgwJMGxbqZvETu9q4QT3g5I5RJQ X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 209.85.213.169 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:14403 Archived-At: Hello, >>> The problem is that the auto-generated =93Standard Library=94 section l= ooks >>> very poor in comparison to the rest of the manual. =A0So we should real= ly >>> 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 =93Standard >>> Library=94). >> >> I could do that pretty easily, but I'm afraid that documentation that >> isn't in the same file as the code would tend to be updated less often >> than documentation in the same file. > > All of our manual except =93Standard Library=94 is maintained this way. = =A0It > takes discipline to keep up-to-date, but it also leads to a better > manual IMO. Okay, I can write documentation this way too. I have a question about this: what is the distinction between the sections "API Reference" and "Guile Modules"? I need to figure out where documentation for different modules goes. >>> However, I believe Thien-Thi=92s Guile 1.4 has good doc for at least so= me >>> of these modules, and it would be great if it could be incorporated. >>> >>> WDYT? >> >> That would be ideal, but I was concerned that the documentation wasn't >> copyrighted by the FSF. Unless Thien-Thi is interested in contributing >> it, of course. > > Yes, I was hoping he would be reading us, let=92s see. =A0;-) After almost a week, I think I'll plan on writing it myself. If someone else happens to contribute documentation, that'll be great too. Thanks, Noah