[Haskell-cafe] Literate programming
dwchandler at stilyagin.com
Sat Jun 12 13:06:39 EDT 2010
On Sat, Jun 12, 2010 at 12:34:37PM -0400, aditya siram wrote:
> It's weird I was just thinking about LP in Haskell this morning. Check out
> John Milliken's dbus-core  written entirely in noweb. It is a pleasure to
> read and I am seriously considering adopting the technique for my Haskell
At my work we've recently started doing something similar to LP. "Real"
LP didn't suite our needs, but we still wanted most of the benefits.
Here are some thoughts, in no particular order:
* We wanted something really easy, so that non-developers / non-latex
people wouldn't be scared off. We decided on textile/markdown with
the ability to embed latex math. We needed docs that were readable
and "nice enough" rather than requiring publication quality
* We wanted source code to be source code, rather than having to
preprocess it before compile or script execution. This suites us
because the code is the product for us, not a paper about the code.
* We wanted something language agnostic. Period. Six different LP tools
for six languages is insane. Noweb would have worked nicely but for
There are a great many LP and LP-like solutions out there, but none of
them that we saw meet the above points. We decided to roll our own
solution by making a simple utility program to make documents from
source code. It simply flips things "inside out" by extracting comments
as the document and putting non-comments in \verbatim blocks. We only
see comments as document when there's only whitespace and no code in
front, as end of line comments tend to be techy comments and not real
If it weren't for the firm desire that source code be source code we
would have went with noweb, despite wanting to keep it simpler than
But our solution is a small amount of effort to get working with a
front-end for "token to EOL" style comments like shell or haskell "--"
comments. Doing front-ends for block comments adds effort, but not so
much. Using Pandoc or similar for actual document processing gives you
lots of options on the back-end and makes everything but the front end
This isn't for everyone, and depends heavily on the three points above.
Darrin Chandler | Phoenix BSD User Group | MetaBUG
dwchandler at stilyagin.com | http://phxbug.org/ | http://metabug.org/
http://www.stilyagin.com/ | Daemons in the Desert | Global BUG Federation
More information about the Haskell-Cafe