On Wed, 2008-02-20 at 16:43 -0800, Conal Elliott wrote:
There was a chat today on #haskell (15:08 to 16:10) about evolving haddock. I'd like to get comments.
The goal is to get the full functionality of a general purpose, programmer-friendly markup language like markdown. One example is image embedding. Another is friendly links (no visible URL).
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. Then people could feed that into whatever other system they like.
Since the old and new doc languages would be quite incompatible, we might want to specify in a .cabal file which language to use.
That's the main thing that worries me. Currently we have the rather nice situation that we have a single standardised markup format that everyone understands. So I very much support the idea of making the markup easier to extract but I think we should be very careful about changing the markup format. The haddock markup format has always been very lightweight and does not assume much about the capabilities of the backend (paper, web, whatever). Duncan