From: "Neil W. Van Dyke" <nwv@neilvandyke.org>
Subject: how authors of add-on modules can package documentation
Date: Sat, 16 Mar 2002 23:18:52 -0500 [thread overview]
Message-ID: <15508.6444.70455.739266@winona.neilvandyke.org> (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
next reply other threads:[~2002-03-17 4:18 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2002-03-17 4:18 Neil W. Van Dyke [this message]
2002-03-17 16:41 ` how authors of add-on modules can package documentation 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=15508.6444.70455.739266@winona.neilvandyke.org \
--to=nwv@neilvandyke.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).