how authors of add-on modules can package documentation

[Neil W. Van Dyke]

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/