+++ 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
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
