[Haskell-cafe] Haddock Markup

[David Waern]

I got the subject line wrong, so I'm reposting this:
====

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, <<! LaTeX stuff here !>>, 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 <<! LaTeX !>> 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