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

[John MacFarlane]

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