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@stilyagin.com | http://phxbug.org/ | http://metabug.org/ http://www.stilyagin.com/ | Daemons in the Desert | Global BUG Federation