[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock

John MacFarlane jgm at berkeley.edu
Mon Apr 8 18:39:48 CEST 2013

+++ John MacFarlane [Apr 05 13 16:04 ]:
> I like markdown and use it all the time.  While I acknowledge the
> problems that have been pointed out, markdown has the advantage of being
> easily readable "as it is" in the source document, and not looking like
> markup.
> But I do want to point out one problem with markdown as a format for
> documentation in Haskell files.  Consider:
> ----------------------------------------------------
> module MyModule
> {-
> # Introduction
> This is my module
> -}
> where
> import System.Environment
> main = getArgs >>= print
> ----------------------------------------------------
> Now try to compile with -cpp, and you'll get an error because of the '#'
> in column 1.  '#' in column 1 is common in markdown (and even
> indispensible for level 3+ headers).
> One could work around this by disallowing level 3+ headers, by allowing
> the headers to be indented, or by introducing new setext-like syntax for
> level 3+ headers, but it is a problem for the idea of using a markdown
> SUPERset.
> John

Let me amplify my original comment with one more observation about
problems using markdown to comment Haskell code.

Markdown blockquotes start with '>' (usually in the leftmost column).
But this causes problems when your source document is bird-style
literate Haskell:

This is my literate Haskell module.  As
someone said:

> literate Haskell is great!

Oops, that will be interpreted by GHC
as code, not comment.

> main = print $ reverse [1,2]

You can work around this by indenting the first '>' one space, which is
still valid Markdown, but it's a bit awkward.  Obviously, we'd want any
Haddock markup successor to work in literate Haskell too.

reStructuredText has fewer potential conflicts and might be a more
sensible choice.  But one would need to write a correct parser for
it.  The pandoc parser doesn't cover 100% of rST, and differs in other
ways from the docutils parser (e.g. it allows markup inside links).
For full compatibility you'd probably want to copy the python module's
parsing algorithm exactly.


More information about the Haskell-Cafe mailing list