Hi Yitzchak,<br><br>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.<br>
<br>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.<br>
<br>Cheers, - Conal<br><br><br><div class="gmail_quote">On Fri, Feb 22, 2008 at 3:25 AM, Yitzchak Gale <<a href="mailto:gale@sefer.org" target="_blank">gale@sefer.org</a>> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div>Conal Elliott wrote:<br>
> Pare the Haddock markup language down to<br>
> very few markup directives, say just 'foo' and<br>
> "Foo.Bar".<br>
<br>
</div>Other critical ones:<br>
<br>
-- | This shows which syntax this text describes.<br>
-- ^ So does this.<br>
<br>
Less critical, but usually not provided by general<br>
markup languages:<br>
<br>
-- $doc A movable documentation chunk.<br>
<br>
If Haddock itself does not parse any other markup,<br>
we must make sure to use markup that does not<br>
lock up its information. It should be something we<br>
have a parser for, or something that has good<br>
tools for turning it into some robust machine-readable<br>
format in a lossless way.<br>
<br>
The reason is that I may want to use a bit of<br>
Haskell in a much larger project that uses some<br>
other markup system for its API documentation.<br>
<br>
So, for example, if I want to integrate the output<br>
into a larger DITA project, there should be an easy<br>
way to do that. Or Doxygen, or whatever else.<br>
<br>
Then Haddock would need to have some way<br>
of outputting its own information nicely, with<br>
embedded chunks of markup. You would read that,<br>
passing each chunk of markup through its parser.<br>
<br>
Truth is, I don't see any such parser for "markdown".<br>
Do you know of one? Maybe we would have to<br>
write one.<br>
<br>
I think that improving the markup capabilities of<br>
Haddock is a minor issue. The main value of<br>
Haddock is its API metadata. Haddock currently<br>
keeps most of that in its bellly, using it secretly<br>
to create its own presentation output. The biggest<br>
improvement would be getting meaningful<br>
machine-readable output.<br>
<br>
Your idea of abstracting out the markup could<br>
actually make that easier, if we keep that goal<br>
in mind as well.<br>
<br>
Thanks,<br>
Yitz<br>
</blockquote></div><br>