Thanks. I guess the best way for me is just writing the formulas as
TeX - code fragments, then it should be easy to adapt
to any potential Haddock extensions to come in the future. At the same
time this notation is readable enough even as plain text in my
opinion.
Peter
On 7 January 2014 03:52, 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. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe