1 Haskell and literate programming

Haskell is one of the few languages that provides native features to support literate programming. In haskell, a literate program is one with the suffix .lhs rather than .hs.

In a literate Haskell program, there are two ways to distinguish between code and non-code portions. You can either prepend all code with a > , (bird style) or surround lines of code with \begin{code} and \end{code} pairs (latex style). For those who know, use and love latex, the latter is the suggested way to go.

You might want to consult the documentation of the "listings" package, to find out whether there's more you can tune to your likings. (Like adding line numbers, etc.) Note that the suggested "literate" option above will replace the given symbols anywhere in the text, including inside strings, which is probably not what one wants.

2.4 Hiding code from Haskell

If you want to hide a \begin{code}...\end{code} block from the compiler, say, if you want to show an example in the text that is not actually part of the source code, you can just add a comment right after the "\begin{code}" statement. This will cause the Haskell parser to treat this block as text, not code:

And the definition of the following function
would totally screw up my program, so I'm not
definining it:
\begin{code}% this is not really code
main :: IO ()
main = print "just an example"
\end{code}
See?

3 Transformation of .lhs-files

Sub-pages here have scripts to convert from the demarcation via > (called "bird style" after Dr. Richard Bird) to \begin{code} and \end{code} pairs

4 Editors

4.1 Multi-mode support in Emacs

Another useful tool for literate programmers is the mmm-mode for Emacs. mmm-mode switches the current major mode of the buffer between two alternatives, depending on the context the cursor is in. If you're in, say, a \begin{code}...\end{code} block, you'll be editing in haskell-mode, but once you leave that block, you'll be editing in latex-mode.

I have managed to cook up a configuration for both literate styles, but surely some Emacs guru can enhance these. To configure mmm-mode for Haskell, add these lines to your .emacs file:

You can activate mmm-mode by running "M-x mmm-ify-by-class" in the buffer. Emacs will prompt you for the class to use, to which should answer literate-haskell-bird or literate-haskell-latex, respectively.

If you want Emacs to activate mmm-mode automatically for certain literate Haskell files, add these lines to it at the end:

4.2 Vim

Take a look at http://urchin.earth.li/~ian/vim. This improves considerably vim's syntax highlighting.
See also Vim for the bits of vim script needed to integrate with the ghc compiler.

5 lhs2TeX

Highly recommended is lhs2TeX at [1], courtesy of Andres Löh. It is designed for typesetting papers about Haskell, but lhs2TeX is easily configured and can make for a powerful preprocessor and documentation generator.

Input to lhs2TeX is a slightly modified .lhs file. One would typically use the standard latex recommendations above, using a \begin{code} and \end{code} pair to demarcate code. Additionally, lhs2TeX provides specialized macros to control the preprocessing.

Note that lhs2TeX and in-line commenting do not seem to mix well.

Since it is able to typeset Haskell formulas in mathematical notation
with LaTeX's math mode you can also use it to create testable
papers. That is the reader can play with the formulas presented in the
paper if he obtains the literate Haskell source code of the paper.