[Haskell-cafe] haddock as a markdown preprocessor

[Duncan Coutts]

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