[Haskell-cafe] Literate programming

[Jason Dagit]

On Sat, Jun 12, 2010 at 9:21 AM, Martin Drautzburg <Martin.Drautzburg at web.de
> wrote:

> Hello all,
>
> Is literate programming something you guys actually do (I only know that
> Paul
> Hudak does), or is it basically a nice idea from days gone by?
>
> In case you do, then how do you do it? Do you use lhs2TeX or what? Do you
> use "bird" style of full-blown LaTeX?
>
> Does any of you use leksah? I failed to see any support for literate
> programming in leksah. It candies the backslashes in e.g.
> \documentclass{article} to λdocumentclass{article}.
>
> In case you don't, then how do you document your code? If you write a paper
> which explains what your code does, then how do you do that?
>

This is all my opinion, but it'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.

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

I think that literate haskell is particularly a bad idea when your goal is
to insert the user manual into a program'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'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'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.

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.

If you are going to use literate haskell, then I believe the latex style is
much nicer because you don't have to prefix every single line with a
character.  Plus when used over email, having lines start with "> " confuses
email clients because that'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.

This is all just my opinion, but hopefully it's still helpful,
Jason
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20100612/a759ff59/attachment.html