+++ Simon Heath [Apr 04 13 13:04 ]:
I humbly suggest reStructuredText rather than Markdown, which is what is used by the Python community for documentation. Since it's specifically made for documentation it may be nicer. But, I don't want to spark a format argument.
There is also the Pandoc program, which is a universal-ish markup- language-converter, conveniently written in Haskell. Might be a place to start for this, regardless of the language chosen: http://www.johnmacfarlane.net/pandoc/
Simon
(Pandoc author here.) It probably wouldn't make sense for a key infrastructure component like Haddock to depend on a behemoth like pandoc. But I could help out with a markdown-superset parser if needed. I have an experimental thing here that could be used as a basis (it's 7x faster than pandoc and uses 1/5 the memory, BSD licensed): https://github.com/jgm/Markdown Another idea: If someone contributed a Haddock markup writer to pandoc, then documentation could be written in markdown (or RST or whatever) and converted automatically to standard Haddock markup. David Lazar has recently contributed a Haddock markup reader, but there is no writer. Note: Creating a writer would be a bit tricky, because Haddock markup isn't expressive enough for many of the constructions pandoc allows -- for example, if I'm not mistaken, you can't have multiple paragraphs inside list items. Decisions would have to be made about how to deal with such cases. There are also a few Haddock constructions that don't correspond to anything in pandoc. John