On Thu, 2008-02-21 at 16:54 -0800, Conal Elliott wrote:
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.
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! :-) 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. 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? Duncan