[Haskell-cafe] Literate programming

[Darrin Chandler]

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 [1] written entirely in noweb. It is a pleasure to
> read and I am seriously considering adopting the technique for my Haskell
> projects.

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

* 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
  requirements above.

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

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

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

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