<br><br><div class="gmail_quote">On Sat, Jun 12, 2010 at 9:21 AM, Martin Drautzburg <span dir="ltr">&lt;<a href="mailto:Martin.Drautzburg@web.de">Martin.Drautzburg@web.de</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
Hello all,<br>
<br>
Is literate programming something you guys actually do (I only know that Paul<br>
Hudak does), or is it basically a nice idea from days gone by?<br>
<br>
In case you do, then how do you do it? Do you use lhs2TeX or what? Do you<br>
use &quot;bird&quot; style of full-blown LaTeX?<br>
<br>
Does any of you use leksah? I failed to see any support for literate<br>
programming in leksah. It candies the backslashes in e.g.<br>
\documentclass{article} to ëdocumentclass{article}.<br>
<br>
In case you don&#39;t, then how do you document your code? If you write a paper<br>
which explains what your code does, then how do you do that?<br></blockquote><div><br></div><div>This is all my opinion, but it&#39;s largely based on my experience with reading lots of haskell source, especially the darcs source which used to be almost completely in the latex style of literate haskell.  These days, very little of it is literate haksell.</div>
<div><br></div><div>I think literate haskell is a mistake for most programs and libraries.  If your goal is to write API level documentation then haddock is more suitable for the task.  The documents created by haddock always have the same layout and consistent look so people new to your API can jump right in and not have to worry about learning how to navigate the docs too much.  And any improvements to haddock as an API level documentation system will instantly benefit your sources.  In other words, you don&#39;t have to maintain any special latex macros or preprocessors to get good API docs.  Another important aspect is that hackage can run haddock on your sources and present the result to people.  This helps for anyone who is interested in your library.</div>
<div><br></div><div>I think that literate haskell is particularly a bad idea when your goal is to insert the user manual into a program&#39;s source code.  My experience with the darcs source was that mostly developers would ignore the huge sections of latex when editing the code and it would get out of sync with the code.  It was too much of a distraction.  People trying to edit the manual often didn&#39;t know Haskell or the darcs source so they would fumble around and resort to grep to find what the wanted to change then they&#39;d have to send a patch that edits haskell files.  This then makes you need to review the patches carefully to review it for edits to code.  That is, documentation changes need less rigorous review typically than code changes, but when the patch mentions modules with core functionality you end up double checking the patch for changes to the core logic.</div>
<div><br></div><div>For papers, emails, and blog posts literate haskell is probably a really good idea.  When you want to write a tutorial style explanation of the code, literate seems to be a win.</div><div><br></div><div>
If you are going to use literate haskell, then I believe the latex style is much nicer because you don&#39;t have to prefix every single line with a character.  Plus when used over email, having lines start with &quot;&gt; &quot; confuses email clients because that&#39;s the most common character inserted for replies.  If it confuses the software people use, you can assume that at least some members of your audience will also get confused.</div>
<div><br></div><div>This is all just my opinion, but hopefully it&#39;s still helpful,</div><div>Jason</div></div>