Conal Elliott wrote:
Pare the Haddock markup language down to very few markup directives, say just 'foo' and "Foo.Bar".
Other critical ones: -- | This shows which syntax this text describes. -- ^ So does this. Less critical, but usually not provided by general markup languages: -- $doc A movable documentation chunk. If Haddock itself does not parse any other markup, we must make sure to use markup that does not lock up its information. It should be something we have a parser for, or something that has good tools for turning it into some robust machine-readable format in a lossless way. The reason is that I may want to use a bit of Haskell in a much larger project that uses some other markup system for its API documentation. So, for example, if I want to integrate the output into a larger DITA project, there should be an easy way to do that. Or Doxygen, or whatever else. Then Haddock would need to have some way of outputting its own information nicely, with embedded chunks of markup. You would read that, passing each chunk of markup through its parser. Truth is, I don't see any such parser for "markdown". Do you know of one? Maybe we would have to write one. I think that improving the markup capabilities of Haddock is a minor issue. The main value of Haddock is its API metadata. Haddock currently keeps most of that in its bellly, using it secretly to create its own presentation output. The biggest improvement would be getting meaningful machine-readable output. Your idea of abstracting out the markup could actually make that easier, if we keep that goal in mind as well. Thanks, Yitz