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

[Ben Gamari]

Johan Tibell <johan.tibell at gmail.com> writes:

> On Thu, Apr 4, 2013 at 9:49 AM, Johan Tibell <johan.tibell at gmail.com> wrote:
>> I suggest that we implement an alternative haddock syntax that's a
>> superset of Markdown. It's a superset in the sense that we still want
>> to support linkifying Haskell identifiers, etc. Modules that want to
>> use the new syntax (which will probably be incompatible with the
>> current syntax) can set:
>>
>> {-# HADDOCK Markdown #-}
>
> Let me briefly argue for why I suggested Markdown instead of the many
> other markup languages out there.
>
> Markdown has won. Look at all the big programming sites out there,
> from GitHub to StackOverflow, they all use a superset of Markdown. It
> did so mostly (in my opinion) because it codified the formatting style
> people were already using in emails and because it was pragmatic
> enough to include HTML as an escape hatch.
>
For what it's worth, I think Markdown is a fine choice for very much the
same reason. RST has some nice properties (especially for documenting
Python), but Markdown is much more common. Moreover, I've always found
RST's linkification syntax a bit awkward.

Cheers,

- Ben