[Haskell-cafe] haddock as a markdown preprocessor

[Duncan Coutts]

On Thu, 2008-02-21 at 13:12 +0000, Alistair Bayley wrote:
> On 21/02/2008, Duncan Coutts <duncan.coutts at worc.ox.ac.uk> 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