[Haskell-cafe] haddock as a markdown preprocessor
conal at conal.net
Thu Feb 21 22:23:30 EST 2008
On Thu, Feb 21, 2008 at 5:37 PM, Duncan Coutts <duncan.coutts at worc.ox.ac.uk>
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Haskell-Cafe