[Haskell-cafe] haddock as a markdown preprocessor

[Conal Elliott]

On Thu, Feb 21, 2008 at 5:37 PM, Duncan Coutts <duncan.coutts at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20080221/f24ebb35/attachment.htm