Re: [Haskell-cafe] haddock as a markdown preprocessor

On Thu, 2008-02-21 at 13:12 +0000, Alistair Bayley wrote:

On 21/02/2008, Duncan Coutts wrote:

...

To be honest I like the fact that haddock's markup is really simple and perhaps somewhat restrictive. A great improvement though would be to make it easy to extract the docs from haddock in a nice format so that the could be re-used in other contexts rather than just generating html api documentation. Haddock does have support for multiple backends, someone just needs to define and write a generic backend that spits out the info that haddock gathers in a machine readable format.

I have probably misunderstood both of you, but I think that Conal proposed that Haddock *input* syntax is largely unchanged; Haddock should be able to *output* markdown, for consumption by pandoc.

(Which I think is also what you're suggesting.)

Yes, I misunderstood, I though Conal was suggesting we extend the haddock input format to allow all the markdown notations. I'd rather not see different packages using different documentation dialects as it makes it much easier for people to contribute if we're all using the same language. I know there is a tension between richer markup for nicer presentation and keeping simple markup for ease of understanding and to present on limited medium like ghci or IDE tooltips. So IMHO we should consider syntactic extensions rather carefully. Though on that topic, we have no consensus as a community about what to use for tutorials or user guides. Consequently there is no support in Cabal etc for those kinds of documentation. GHC, Cabal and c2hs amongst others use docbook but it's a horrible format to write and the tools to process it are very finicky (we apparently have to hard code paths to specific versions of xslt stylesheets). Duncan