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