I guess there was some confusion about the haddock-as-preprocessor idea.  Here's another try:

Pare the Haddock markup language down to very few markup directives, say just 'foo' and "Foo.Bar".  (Of course, Haddock continues to read and process type signatures and module import & export specs.)  Compose this slimmed down Haddock with a more mainstream and powerful markup language/processor like markdown/pandoc.  How to compose?  By having Haddock translate its markdown extensions into markdown and pass through all the rest.

The goal redesigning for composability is that we get more for less.  Haddock can focus on its speciality, namely hyperlinked Haskell code documentation, and pandoc on its, namely human-writable and -readable prose with modern features (images, friendly hyperlinks, smart quotes & dashes, footnotes, super- and subscripts, pretty math, bibliography-style link specs, etc).  Haddock development can focus its resources on Haskell-specific functionality, and we library writers can still use a full-featured mark-up language.

I love Haddock's Haskell-smarts, and I love (extended) markdown's features and usability.  Currently, I have to choose between them, and I'd rather get both at once.

We can take this composability idea further and plug in other nifty tools like hscolour and lhs2TeX.  And a new tool that hyperlinks and annotates source code in a variety of ways.  For instance, hover over an identifier to see its type and doc string in a pop-up, or click to jump to the source code (also annotated with type, doc, and source links).  And other tools we haven't yet thought of.

Cheers,  - Conal


On Thu, Feb 21, 2008 at 5:12 AM, Alistair Bayley <alistair@abayley.org> wrote:
On 21/02/2008, Duncan Coutts <duncan.coutts@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.)

Alistair