Literate Haskell (.lhs) and Haddock

Question

At the moment I'm only using Haddock but after seeing some really interesting examples (e.g. this gist) of literate Haskell, I'm interested in trying it out in a project.

The questions I got, are:

• What do you write as Haddock comments and what do you write in the literate part?

• How do you scale literate programming to multiple files? Can anyone point me to an example where literate programming is used in a package with multiple modules? What is your experience of using literate programming in larger packages?

• Which flavour (markdown, latex, ...) of literate Haskell is preferred?

• Why are you programming in literate Haskell or plain vanilla Haskell? Are you programming in both styles and if so why?

• Do you prefer block-style (\begin{code}) or Bird-style (>)? Why?

Answer 1

I used to write a lot of literate programs.

What do you write as Haddock comments and what do you write in the literate part?

The external API documentation goes into the Haddock comments. Everything else goes into the literate part. "Everything else" might include:

• Internal invariants of data structures
• Why you are doing things this way
• What the design of the code is
• Why this design was chosen, what other designs were tried and found wanting

How do you scale literate programming to multiple files?

The same way you scale a large LaTeX document to multiple files: one file per module, then a giant file that \includes them all.

Can anyone point me to an example where literate programming is used in a package with multiple modules?

It's not Haskell, but the Quick C-- compiler is a large functional program that is written using literate programming.

What is your experience of using literate programming in larger packages?

Literate programming works very well for documenting tricky, difficult, or complex modules. For most simple modules, the external API documentation (e.g., Haddock) is enough. And no literate program is really going to give you the big picture of a design that contains more than a dozen modules. For that you need other tools and techniques.

Which flavour (markdown, latex, ...) of literate Haskell is preferred?

If you're making such a major investment, I'd definitely go with LaTeX just because of the math capability, and the generally greater power of the tool.

Why are you programming in literate Haskell or plain vanilla Haskell? Are you programming in both styles and if so why?

My Haskell codes are almost always all plain vanilla, for two reasons:

• I work with senior people who have more Haskell experience, and they have abandoned literate Haskell. Only the very oldest modules in their system have any chance of being .lhs.

• For Haskell, literate programming is kind of superfluous. One of the big benefits of a literate-programming tool is that you are freed from any constraints that the compiler or language definition might put on the order in which your code appears. But Haskell has almost no such constraints: there's no definition before use, and for a typical function definition I have the choice of let-binding or where-binding auxiliary names (or both). Literate programming was never just about fancy comments, and with "literate" Haskell that's about all you get. It's not worth the bother.

Do you prefer block-style (\begin{code}) or Bird-style (>)? Why?

I strongly prefer block style:

• It's roughly compatible with every other literate-programming tool on the planet. (Bird tracks are unique to Haskell.)

• My editor copes better with block style.

Answer 2

If you intend to share programs on the internet, I've found a combination of literate haskell in markdown style with mathjax to be a great combination. The program "Pandoc" is seriously brilliant for taking this "markdown+lhs" to any format you desire, including PDF or HTML. If you tell Pandoc to output to HTML, you can use the -mathjax (or other similar flags if you prefer) to have your latex math formulas render.

When using this style, I find bird style to be preferable because it just is more readable to me and seems to fit along with the markdown style better.

The great thing about using Pandoc with markdown is that you can add citations to your code, math formulas, and have a really portable format. You can build something that resembles a scientific research paper but is executable and can also be posted to blogs/wikis/websites.

To give an alternative point to Norman where he says that literate programming is useful for clearer code arrangement, it could be argued that Haskell is expressive enough that the problems you solve with the code are actually interesting and can really benefit by being surrounded with explanatory text. Think of a mathematical research paper. Good papers in pure mathematics have a lot of text to explain the motivation or higher-level interpretations of what the mathematical notation means. In a paper about the Navier-Stokes equations, for example, it would be super useful to surround the notation of the equations with text explaining how it relates to Newton's conservation of momentum.

In summary, I have had good success with, and recommend, using markdown+lhs style, dollar signs to embed latex math formulas, bird style, and pandoc. I would recommend writing programs as if they were research papers and treat the haskell itself as you would mathematical expressions in a research paper.