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

[John MacFarlane]

+++ 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.

John