Mateusz Kowalczyk fuuzetsu at fuuzetsu.co.uk
Tue Jan 7 02:52:12 UTC 2014

On 07/01/14 01:42, Carter Schonwald wrote:
> I would really love to use MathJax in the haddock HTML backend. Is there
> any way (however hacky) that I could do that?

I looked up how MathJax is used and as far as I can tell, it's just
the case of putting the MathJax JavaScript header into the file,
for example the synopsis box.

While I prefer JavaScript-free web I think that for viewing on
Hackage, it'd be possible to just stick the header into the generated
files and be done with it. Here are some caveats:

* You suddenly allow for part of documentation to be rendered by
someone else, over the Internet. The problem is that documentation
suddenly becomes worse for everyone browsing without JavaScript or
browsing locally, without an Internet connection. Embedding images
avoids both of these problems.

* With the wealth of characters you're likely to use while writing
LaTeX, it would clash with existing Haddock syntax sooner or later
so this would have to be handled. I spent my summer working on
Haddock parser and the new version allows you to escape things
properly but the currently used one is very limited in that aspect.
You'd probably end up having to introduce some kind of ‘verbatim’
block to Haddock's syntax which tells it to just take things at face
value. It'd not be too hard with the new parser. We're having
problems getting the new parser merged however (problems validating
GHC to check that we haven't broken everything ever).

* This touches on frequently overlooked problem: Haddock targets more
than just the HTML back-end. We also have the LaTeX back-end and the
Hoogle back-end. This is why we don't allow things like verbatim
HTML in the markup, it doesn't make sense for anything but HTML.
Admittedly, LaTeX back-end could just generate the maths itself but
we then suddenly have to change the ‘verbatim’ block to the ‘LaTeX’
block. It's also unclear how Hoogle back-end would deal with this.
Even if we add the ‘LaTeX structure‘ to Haddock, I'm afraid that it
might end up with people just writing LaTeX for their documentation
which is useless for anyone not using that back-end.

So, yes, it'd be possible but it'd be very hacky. Not from the code
aspect of things, but from the design aspect of it.

Perhaps it'd be possible to have pieces of documentation targeting
specific back-ends, kind of like internal Haddock pragma if you will,
which would allow the user to write differently looking docs for each
back-end. At this point however, it becomes clunky to use, horrible to
maintain and simply including images in your docs is the easier way
out, especially because you're no longer limited by what Haddock can
do. I recommend against this kind of thought and I expect that most
people that have worked on Haddock would agree.