On Thu, Feb 21, 2008 at 5:37 PM, Duncan Coutts <duncan.coutts@worc.ox.ac.uk> wrote:
> So the advantage of passing the rest through uninterpreted is that
> markdown then interprets it and we get lots of cool markup for free, the
> disadvantage is that we get lots more markup that I don't
> understand! :-)
Thanks for this summary, Duncan.
> There really is something to be said for being able to download a random
> package, read the code at the documentation markup and be able to
> understand it and modify it. If it's a simple common language like we
> have at the moment we can do that. I worry about loosing that property.
Have you looked at markdown? It's a popular and well-documented format
and based on common conventions. I bet you'd have no trouble learning
it, and I bet many other Haskell programmers *already* know it. (BTW,
I just noticed that this mail message is in written in markdown.)
> So yes we could make haddock not care so much and pass everything
> through and then people could do whatever they liked with new markup
> formats but I wonder if we cannot find a common language that we can all
> agree on. Are there any particularly cool things in markdown that lots
> of haskell developers want to use in their api documentation?
My previous note listed some (pandoc-extended) markdown features I use
regularly (while blogging) that are missing in Haddock. If I could,
I'd use them in my code documentation.
I'd like to hear from others about what markup features you'd like to
have in your code documentation but aren't supported by Haddock.
Cheers, - Conal