[racket] Getting started with Scribble

On Sat, Mar 17, 2012 at 11:44 AM, Eli Barzilay <eli at barzilay.org> wrote:

> Note that what Haskell does is *semi*-literate-programming, something
> that has little to do with literate programming.  Neil Van Dyke is
> working on a tool that is going to be more like
> semi-literate-programming.
>
>
I understand that literate programming in the Knuth-defined sense allows
separation of function bodies into smaller chunks, and allows complete
freedom over organization.  In a language like Racket where function
definitions can be in any order, you have pretty good flexibility to
organize your code top-down or bottom-up, moving things where it makes
sense to build an explanation.  So the main thing you lose with a
lighterweight tool is the ability to break up functions into smaller
pieces.  Racket functions are often so small, that's not a huge
limitation.  So yes, lp is more powerful, but just being able to invert the
relative importance of documentation vs code and read the file both ways in
a linear top-to-bottom fashion is valuable.

semi-literate-programming seems an apt name.

I don't think Javadoc would even qualify for that label though.  In my
mind, "semi-literate" at least implies a focus on building a narrative
exposition of why the functions work the way they do, not just API
documentation.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20120317/8b704f18/attachment.html>