% Literate Programming with pandoc and lhs2tex
% Tillmann Rendel (Updated by Matthew Pickering)
% November 2015

pandoc-lit supports literate programming by combining two
excellent tools: [pandoc] for text processing, and [lhs2TeX]
for source code formatting. pandoc-lit's input files are written
in markdown+lhs, and its output is LaTeX code ready to be
processed by lhs2tex.

[pandoc]: http://johnmacfarlane.net/pandoc/
[lhs2TeX]: http://people.cs.uu.nl/andres/lhs2tex/

I use pandoc-lit to write research papers and prepare
presentation slides, and I plan to use it for my Ph.D. thesis. It
has been used by a colleague to prepare a presentation, so it
runs one computers other than mine, too. So while I think it is
quite usable already, it is by no means stable, and currently,
using it essentially requires some amount of hacking on it.

Installation
============

Install the package from hackage. It provides an executable called `pandoc-lit`.

    cabal install pandoc-lit

Documentation
=============

pandoc-lit works by traversing the [pandoc] AST and reformatting certain elements
so that they are suitable to be processed by [lhs2TeX].

## Transformations

All special lhs2TeX characters are escaped automatically (for example `|`).

### Inline Code

Inline code fragments are directly translated to lhs2TeX inline code fragments.

```
This is some text with the variable `x` in the middle
-->
This is some text with the variable |x| in the middle
```

### Code Blocks

Code blocks are translated to either the `code` or `spec` environment. If
`literate` is amongst the code block's classes then it will be translated to a
`code` environment, otherwise the `spec` environment.

```
\`\`\`
foo = x
\`\`\`
-->
\begin{spec}
foo = x
\end{spec}
```

```{literate}
\`\`\`
foo = x
\`\`\`
-->
\begin{code}
foo = x
\end{code}
```

### Raw LaTeX

Raw LaTeX commands are escaped and passed through.


## Options

There are also a large number of options which can be used to configure the final
document.

None available, but try `pandoc-lit --help` for an overview of
command-line options, or watch this [lightning talk at the
Haskell Implementors Workshop].

[lightning talk at the Haskell Implementors Workshop]: http://www.vimeo.com/15481736

Example
=======

The paper and presentation slides about [invertible syntax
descriptions] were produced with pandoc-lit. This short guide
explains how to recompile the pdfs from sources.

[invertible syntax descriptions]: http://www.informatik.uni-marburg.de/~rendel/unparse/

First, install pandoc-lit:

    wget http://www.informatik.uni-marburg.de/~rendel/pandoc-lit/pandoc-lit-0.1.tar.gz
    tar -xzf pandoc-lit-0.1.tar.gz
    cd pandoc-lit-0.1
    cabal install
    cd ..
    rm -r pandoc-lit-0.1

The following commands should download the files necessary to
compile the paper and the presentation slides:

    md pandoc-lit-test
    cd pandoc-lit-test
    wget http://www.informatik.uni-marburg.de/~rendel/unparse/sources.zip
    unzip sources.zip
    wget http://www.informatik.uni-marburg.de/~rendel/unparse/scrartcl.template
    wget http://www.sigplan.org/sigplanconf.cls
    wget -P Talk http://www.informatik.uni-marburg.de/~rendel/unparse/beamer.template

The paper
---------

The paper consists of the primary file `Unparse.lhs` which uses
lhs2tex `%include` directives to include a bunch of secondary
files (`Iso.lhs`, `TH.lhs` and `Evaluation.lhs`). All of these
files use pandoc `markdown+lhs` mixed with lhs2tex directives. We
need to run pandoc-lit on each of the files to convert the
pandoc `markdown+lhs` into `latex+lhs`, but leaving the lhs2tex
directives in place, and encoding everything according to
lhs2tex's input format (e.g., escaping `|` into `||`). The transformed
files will be written into a separate `build` directory.

We start with the secondary files. We use the `--comments` flag to
preserve TeX-style `%...` comments, including lhs2tex directives.

    md build
    pandoc-lit --comments Iso.lhs > build/Iso.lhs
    pandoc-lit --comments TH.lhs > build/TH.lhs
    pandoc-lit --comments Evaluation.lhs > build/Evaluation.lhs

For the primary file, we need to add a couple of options. We use
`--template` to select `scrartcl.template` which contains the
document preamble. The `--abstract` flag converts a section with
header `"Abstract"` into an `abstract` environment. And finally
`--variable=sigplanconf:1` sets a variable for pandoc's template
engine. This variable is tested in `scrartcl.template`.

    pandoc-lit --template scrartcl.template --abstract --variable=sigplanconf:1 --comments Unparse.lhs > build/Unparse.lhs

Now, the four `*.lhs2tex` files in `build` are ready to be
processed by lhs2tex. A single call will suffice, since lhs2tex
will process the `%include` directives.

    cd build
    lhs2tex Unparse.lhs > ../paper.tex
    cd ..

Lhs2tex should have produced a single file `paper.tex` which
contains the full paper. We can `latex` or `pdflatex` this file
as usual.

The presentation slides
-----------------------

The presentation slides use the LaTeX-package `beamer`. Like the
paper, the presentation slides consist of a primary file
(`Talk/Main.lhs`) which uses lhs2tex `%include` directives to
include some secondary files (`Talk/AST.lhs`,
`Talk/OnlyParsing.lhs`, `Talk/OnlyPrinting.lhs` and
`Talk/Syntax.lhs`). But for the paper, instead of processing the
secondary files separately to be included by lhs2tex, pandoc-lit
will process the `%include` directives, producing a single input
file for `lhs2tex`.

    cd Talk
    pandoc-lit --title-page --template beamer.template --eval .. --comments --beamer --process-includes Main.lhs > slides.lhs

The `--title-page` option replaces the first section called
`Title Page` by a title frame (using `\maketitle`). The
`--template` option selects `beamer.template` for the preamble.
The `--eval ..` option activates processing of `\eval{...}`
directives with source directory `..`. Using `..` as source
directory is necessary to process module names such as `Iso` or
`Talk.Syntax` correctly. The `--comments` option preserves
TeX-style `%...` comments. The `--beamer` option activates
beamer-specific processing. For instance, subsections in the
input are replaced by `frame` environments in the output.
Finally, `--process-includes` activates the processing of
`%include` directives.

Pandoc-lit should have produced a single file `slides.lhs` which
contains all of the presentation slides. This file can be
processed by lhs2tex.

    lhs2tex slides.lhs > slides.tex

The preamble in `beamer.template` is targeted at XeTeX, so we
need to further process `slides.tex` by `xelatex`.

Feedback
========

Feedback, patches, rants, questions, insights etc. are welcome.
Send to [Tillmann Rendel].

[Tillmann Rendel]: mailto:[email protected]