posted 2013-07-27
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.
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.
If you want to start a new paragraph, you have to put a single period on a new line all by itself.
This is weird.
And undocumented!
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,
 , for the leading space character. After
that, regular spaces won't be trimmed.
Examples:
$ ./foo --arg1 \
--arg2
(That probably won't be lined-up due to the variable-width font, but you get the idea.)