[Haskell-cafe] haddock as a markdown preprocessor

[Conal Elliott]

Hi Yitzchak,

About "-- |", "-- ^", and "-- $doc", we might call them "markup
meta-directives", since they delimit the text to be preprocessed and then
produced as markup.  The meta-directives and the "-- " line prefixes would
be removed in the process.

As for producing machine-readable API metadata, I hadn't been thinking along
those lines, and I enthusiastically agree with you.  Further factor haddock
into a metadata extractor and a documentation generator.

Cheers,  - Conal


On Fri, Feb 22, 2008 at 3:25 AM, Yitzchak Gale <gale at sefer.org> wrote:

> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20080222/ef49ed6d/attachment.htm