unofficial mirror of guile-devel@gnu.org 
 help / color / mirror / Atom feed
* how authors of add-on modules can package documentation
@ 2002-03-17  4:18 Neil W. Van Dyke
  2002-03-17 16:41 ` Evan Prodromou
  2002-04-03  3:52 ` Thien-Thi Nguyen
  0 siblings, 2 replies; 7+ messages in thread
From: Neil W. Van Dyke @ 2002-03-17  4:18 UTC (permalink / raw)


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


^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2002-04-03  5:29 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2002-03-17  4:18 how authors of add-on modules can package documentation Neil W. Van Dyke
2002-03-17 16:41 ` Evan Prodromou
2002-03-17 23:35   ` Neil Jerram
2002-03-17 23:45     ` Neil Jerram
2002-03-18  2:04     ` Evan Prodromou
2002-04-03  5:29       ` Thien-Thi Nguyen
2002-04-03  3:52 ` Thien-Thi Nguyen

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).