[Haskell-cafe] haddock as a markdown preprocessor

[Yitzchak Gale]

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