[plt-scheme] Vision behind Scribble

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.

Personally, at least for self-contained libraries, I find that embedding 
documentation within the code works well enough for my purposes:

http://www.neilvandyke.org/csv-scm/csv.scm
http://www.neilvandyke.org/csv-scm/csv.pdf
http://www.neilvandyke.org/csv-scm/csv.html
csv.plt has a generated old-style PLT Help Desk index file, too.

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.

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.

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."


Grant Rettke wrote at 03/17/2008 12:41 PM:
> On Mon, Mar 17, 2008 at 11:29 AM, Noel Welsh <noelwelsh at gmail.com> wrote:
>   
>>  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.
>>     
>
> I see.
>
> I've never tried so I don't know what works and want doesn't :)
>   

-- 
http://www.neilvandyke.org/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20080317/c68ff15a/attachment.html>