[Haskell-cafe] haddock as a markdown preprocessor

[Duncan Coutts]

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