<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
I think you'll find that Schemers are a diverse bunch -- there are very
few things that have an accepted One True Way. This diversity extends
to documentation methods. Fortunately, the Scheme universe is flexible
enough to accommodate everyone.<br>
<br>
Personally, at least for self-contained libraries, I find that
embedding documentation within the code works well enough for my
purposes:<br>
<br>
<a class="moz-txt-link-freetext" href="http://www.neilvandyke.org/csv-scm/csv.scm">http://www.neilvandyke.org/csv-scm/csv.scm</a><br>
<a class="moz-txt-link-freetext" href="http://www.neilvandyke.org/csv-scm/csv.pdf">http://www.neilvandyke.org/csv-scm/csv.pdf</a><br>
<a class="moz-txt-link-freetext" href="http://www.neilvandyke.org/csv-scm/csv.html">http://www.neilvandyke.org/csv-scm/csv.html</a><br>
csv.plt has a generated old-style PLT Help Desk index file, too.<br>
<br>
The narrative structure, such as it is, of this documentation tends to
be bottom-up, as the ordering of code definitions tends to be. This is
awkward in the HtmlPrag documentation, but could be mitigated by
showing off a big-picture example in the Introduction.<br>
<br>
If you'd like to play with embedded documentation, it would not be
difficult to write a tool that assembled a
Scribble document from comments embedded in a Scheme source file.<br>
<br>
If you have related definitions scattered among multiple Scheme files,
and you might want a mechanism for talking about how the chunks of
documentation from different files relate. I've avoided that, but the
first thing I would Google for is "literate programming."<br>
<br>
<br>
Grant Rettke wrote at 03/17/2008 12:41 PM:
<blockquote
cite="mid:756daca50803170941k1abd98cdq2fc11b3f0e53345f@mail.gmail.com"
type="cite">
<pre wrap="">On Mon, Mar 17, 2008 at 11:29 AM, Noel Welsh <a class="moz-txt-link-rfc2396E" href="mailto:noelwelsh@gmail.com"><noelwelsh@gmail.com></a> wrote:
</pre>
<blockquote type="cite">
<pre wrap=""> I don't know why Matthew made that decision, but having written
Javadoc documentation, and attempted to do the same in Scheme, I have
found it doesn't work well.
</pre>
</blockquote>
<pre wrap=""><!---->
I see.
I've never tried so I don't know what works and want doesn't :)
</pre>
</blockquote>
<br>
<div class="moz-signature">-- <br>
<a class="moz-txt-link-freetext" href="http://www.neilvandyke.org/">http://www.neilvandyke.org/</a>
</div>
</body>
</html>