Hi everyone, 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. As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. There was also a thread about Haddock markup on haskell-cafe@ about a year ago, which originated with the interesting idea of using Markdown (or a Pandoc-extended version of it) instead of the current language: http://www.mail-archive.com/haskell-cafe@haskell.org/msg38054.html I think the original idea there is pretty nice, but let's first focus on the current markup language in order to answer Lennart's question. That thread contains some useful opinions on this matter, also. So, any comments? :) David