On Fri, 2009-02-06 at 01:35 +0100, David Waern wrote:
I received this question from Lennart Augustsson (via Simon M) and thought I'd send out an inquiry to the Haskell community in general (Lennart, I hope you don't mind):
Lennart writes:
We have some local patches for haddock that extends the <<blah>> syntax so you can put TeX formulae in the documentation. It looks like, <>, but I'd like to extend it so you can process the string with any command.
Are you interested in folding this into the main branch?
So the question is about extending the Haddock markup language.
When modifying the language we should think about the tension between familiarity, presentation features (pictures, math, whatever) and visual portability across different mediums (HTML, ghci, IDE tooltips, etc). And here I should say that Haddock already supports pictures using the << url >> syntax.
IMHO, adding <> for TeX math is fine, because:
- math in documentation is often useful - if you're going to write math, you need a format, even when the medium is plain text as in ghci. - TeX formulae seem to be relatively widely used and understood.
My comment isn't related to the wider implications of third-party hooks into Haddock, but just for the (La?)TeX stuff itself. I think that the TeX *language* is great for writing mathematics, but that we should be wary of blindly incorporating TeX *output* into Haddock. Most of Haddock's documentation is currently HTML-based, and if we add TeX mathematics in the usual way (i.e. embedding images) it is very ‘inaccessible content’ (no selection, scaling, and a myriad of other small niggles) compared to the rest of the HTML file. My thoughts would be to use the TeX engine itself for when generating high-quality PDF documentation, and have something else translate TeX to (e.g.) MathML for the HTML pages. There are various programs to do this (or it could be done in Haskell :D!) Thanks, - George