On Thu, Feb 21, 2008 at 5:37 PM, Duncan Coutts
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