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.