Literate programming
Literate programming was invented / coined / started by Dr. Donald Knuth. In, fact if you asked Dr. Knuth what his favourite programming language was, you would be told CWEB - which is a literate programming tool combining C and tex.
Latex suggestions for literate programming
In the majority of these suggestions, you can simply write:
\begin{code}
qsort [] = []
qsort (x:xs) = qsort [y | y<-xs, y>x] ++ [x] ++ qsort [y | y<-xs, y<=x]
\end{code}
and the code will be formatted as you requested.
The advantage: Source code and documentation are consistent! The code environment is understood by Haskell compilers, so you can run your documentation files directly.
Verbatim package
One can always simply use verbatim mode which will format the code "as-is".
Use verbatim:
\usepackage{verbatim} \newenvironment{code}{\footnotesize\verbatim}{\endverbatim\normalsize}
Listings package
Another alternatative is to use the latex-package listings, which allows you to do much more customization of the output:
\usepackage{listings} \lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small}}{}
You can configure the appearance of the listings quite a bit! Some people find these settings to be the most satisfying:
\usepackage{listings} \lstloadlanguages{Haskell} \lstnewenvironment{code} {\lstset{}% \csname lst@SetFirstLabel\endcsname} {\csname lst@SaveFirstLabel\endcsname} \lstset{ basicstyle=\small\ttfamily, flexiblecolumns=false, basewidth={0.5em,0.45em}, literate={+}{{$+$}}1 {/}{{$/$}}1 {*}{{$*$}}1 {=}{{$=$}}1 {>}{{$>$}}1 {<}{{$<$}}1 {\\}{{$\lambda$}}1 {->}{{$\rightarrow$}}2 {>=}{{$\geq$}}2 {<-}{{$\leftarrow$}}2 {<=}{{$\leq$}}2 {=>}{{$\Rightarrow$}}2 {\ .}{{$\circ$}}2 {\ .\ }{{$\circ$}}2 {>>}{{>>}}2 {>>=}{{>>=}}2 {|}{{$\mid$}}1 }
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.
Hiding code from Latex
If you want to hide some code, you can e.g. define:
\long\def\ignore#1{}
Auxiliary functions can be hidden as follows:
\ignore{ \begin{code} help = putStr "Help me, what is this LiterateProgramming thing??" \end{code} }
Thanks to Wolfram Kahl, Oliver Braun and the people of the German TeX-newsgroup.
Ciao, Steffen Mazanek
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?
Transformation of .lhs-files
To convert a Haskell script file which uses bird style to \begin{code}...\end{code} style use one of the following scripts:
awk:
# bird2code.awk ^[^>] || ^$ {print; next} ^> { print "\\begin{code}" sub(/^> /,"") print rc = getline while(($0 ~ ^>) && (rc > 0)) { sub(/^> /,"") print rc = getline } print "\\end{code}\n" }
Or in sed:
# bird2code.sed ^> !p ^> { i\ \\begin{code} :loop N /\n>[^\n]*$/{ b loop } s/^> // s/\(\n\)> /\1/g s/\n$// a\ \\end{code}\ p }
Thanks to Peter Tillier from the comp.lang.awk newsgroup.
Editors
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:
(add-hook 'haskell-mode-hook 'my-mmm-mode) (mmm-add-classes '((literate-haskell-bird :submode text-mode :front "^[^>]" :include-front true :back "^>\\|$" ) (literate-haskell-latex :submode literate-haskell-mode :front "^\\\\begin{code}" :front-offset (end-of-line 1) :back "^\\\\end{code}" :include-back nil :back-offset (beginning-of-line -1) ))) (defun my-mmm-mode () ;; go into mmm minor mode when class is given (make-local-variable 'mmm-global-mode) (setq mmm-global-mode 'true)) (setq mmm-submode-decoration-level 0)
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:
% ----- Configure Emacs ----- % % Local Variables: *** % mode: latex *** % mmm-classes: literate-haskell-latex *** % End: ***
This is, what the my-mmm-mode hook does, by the way.
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.
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. 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.