[Haskell-cafe] Haddock Markup

[George Pollard]

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, <<! 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.

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
Url : http://www.haskell.org/pipermail/haskell-cafe/attachments/20090206/053abf08/attachment.bin