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 <[EMAIL PROTECTED]> 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 >
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe