From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Neil W. Van Dyke" Newsgroups: gmane.lisp.guile.devel Subject: how authors of add-on modules can package documentation Date: Sat, 16 Mar 2002 23:18:52 -0500 Sender: guile-devel-admin@gnu.org Message-ID: <15508.6444.70455.739266@winona.neilvandyke.org> NNTP-Posting-Host: localhost.gmane.org X-Trace: main.gmane.org 1016338931 5489 127.0.0.1 (17 Mar 2002 04:22:11 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Sun, 17 Mar 2002 04:22:11 +0000 (UTC) Original-Received: from fencepost.gnu.org ([199.232.76.164]) by main.gmane.org with esmtp (Exim 3.33 #1 (Debian)) id 16mSBO-0001QR-00 for ; Sun, 17 Mar 2002 05:22:10 +0100 Original-Received: from localhost ([127.0.0.1] helo=fencepost.gnu.org) by fencepost.gnu.org with esmtp (Exim 3.34 #1 (Debian)) id 16mSAL-0003WE-00; Sat, 16 Mar 2002 23:21:05 -0500 Original-Received: from dsl092-071-029.bos1.dsl.speakeasy.net ([66.92.71.29] helo=winona.neilvandyke.org) by fencepost.gnu.org with esmtp (Exim 3.34 #1 (Debian)) id 16mS83-0002uH-00 for ; Sat, 16 Mar 2002 23:18:43 -0500 Original-Received: from nwv by winona.neilvandyke.org with local (Exim 3.35 #1 (Debian)) id 16mS8C-0005R1-00 for ; Sat, 16 Mar 2002 23:18:52 -0500 Original-To: guile-devel@gnu.org X-Mailer: VM 7.01 under Emacs 21.1.1 Errors-To: guile-devel-admin@gnu.org X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.0.5 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Developers list for Guile, the GNU extensibility library List-Unsubscribe: , List-Archive: Xref: main.gmane.org gmane.lisp.guile.devel:91 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:91 If anyone is thinking about different ways that authors of reusable Guile add-on modules can document their code, we should compare notes. A year ago I kludged up a filter called "Funcelit" (as in "functionally-illiterate programming") that extracts Texinfo fragments from a Guile Scheme file, tweaks them a bit, and glues them together with some boilerplate to generate a Texinfo file. The resulting Texinfo file can be translated to Info, HTML, PS/PDF formats using the usual Texinfo tools, but the output will be formatted as an article rather than as a book. Originally I had the filter treat each module as a chapter in a book, but then I decided to focus on loosely-coupled standalone modules rather than on a monolithic collection of modules. Chapter formatting could be added back in as an option. One reason I like having full docs in the source file itself as human-readable comments is that then a module can be shared simply by passing around a single Scheme source code file. This file can be immediately viewed and modified by the person who receives it (i.e., there is no "tar" or package manager to deal with, no source files getting hidden away elsewhere deep in some filesystem tree, etc.). I think this kind of accessibility of source files is one of the reasons that so many people have gotten started writing their own Emacs Lisp extensions. Of course, a holder of a source file always has the option of running the Funcelit filter on the source file generate pretty Info/HTML/PS/PDF documentation. Funcelit is not yet released, as I've been adapting it as I use it in writing modules, and didn't want to be constantly changing the input format on people. I'll probably polish it up and release it not too long after the release of Guile 1.6. (I was reminded of Funcelit tonight because I finally kludged up some Emacs font-lock support for Funcelit comments. Screenshot at "http://www.neilvandyke.org/weblog/funcelit-fontified.png".) -- Neil W. Van Dyke http://www.neilvandyke.org/ _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel