[Haskell-cafe] Haddock - How to write formulas ?

[Mateusz Kowalczyk]

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,
right? We already use JavaScript on the Haddock-generated HTML pages,
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.

In conclusion, if you want maths in your comments, use images.

--
Mateusz K.