michael orlitzky

Using Haddock markup in a Cabal file

What are these things?

Haddock is a tool for automatically generating Haskell API documentation. Cabal is a build system, sort of like GNU Autotools, for Haskell projects.

If you don't write programs in Haskell, you don't care about this article.

The Problem

When Cabal generates the documentation for your program, the main summary or description of what it does is pulled from the description field of the <project>.cabal file. According to the Cabal user guide,

description: freeform

Description of the package. This may be several paragraphs, and should be aimed at a Haskell programmer who has never heard of your package before.

For library packages, this field is used as prologue text by setup haddock, and thus may contain the same markup as haddock documentation comments.

That last part is naturally a lie; you need several tricks to emulate Haddock markup in the description field of a cabal file. Here we go.

Line Breaks (Paragraphs)

If you want to start a new paragraph, you have to put a single period on a new line all by itself.

Input:

1
2
3
4
description:
  This is weird.
  .
  And undocumented!

Output:

This is weird.

And undocumented!

Leading Whitespace

If you want to put blank spaces at the beginning of a line, Yossarian, you cannot begin the line with a space, because then all leading whitespace will be stripped.

The trick here is to use an numeric XHTML reference, &#x20;, for the leading space character. After that, regular spaces won't be trimmed.

Input:

1
2
3
4
5
description:
  Examples:
  .
  $ ./foo --arg1 \
  &#x20;       --arg2

Output:

Examples:

$ ./foo --arg1 \
              --arg2

(That probably won't be lined-up due to the variable-width font, but you get the idea.)