Proposal for Mathjax

[idontgetoutmuch]

Consider this a proposal for how we support math in haddock. I've only done inline math so far but display math shouldn't be much harder. See #382 for more discussion.

[cartazio]

The one concern I have is how the rendering will look when the viewer doesn't have in working Internet or if the cdn url changes. But maybe those are none issues

[bkaestner]

I have the following concerns:

1. $$ in LaTeX is considered wrong,
2. $$ was used for block/display math (not inline), but you're using it for inline math code (that even conflicts with MathJax),
3. $$ is a valid Haskell operator name and might conflict in several situations where one forgot to use the correct code markup,
4. the variant for inline code in LaTeX \( ... \) is rather unlikely to conflict with existing code and might be more suitable.

[idontgetoutmuch]

@cartazio it will look like this so not too disastrous.

[idontgetoutmuch]

@bkaes very interesting - I am clearly a TeX dinosaur ;-) No more $$...$$ for me.

[hvr]

@idontgetoutmuch one could make the matjhax js url (optionally) configurable via a CLI option, that way ppl who need it could build local haddock docs which don't require internet access...

[ocharles]

I do think that is pretty disastrous if you don't have a working internet connection, but I like the idea of being able to bundle in a local Mathjax source.

[idontgetoutmuch]

Ok so my proposal is this: we use (...) for inline, [...] for display and allow the mathjax url to be configured via a CLI option. I will try and finish this off next weekend.

For info I am adding a link to the reddit comments: http://www.reddit.com/r/haskell/comments/366fgo/proposal_for_mathjax_pr_haskellhaddock397/

But please don't let me stop anyone else finishing this off :-)

[bkaestner]

@idontgetoutmuch Do you mean \( … \) and \[…\]? Only brackets might lead to MathJax everywhere (probably formatting, right)?

[idontgetoutmuch]

@bkaes yes I didn't realise that github wanted me to escape \

[Fuuzetsu]

Do we need two different syntax constructs for this? Can't it work like @ does?

EDIT: I don't have time to look at anything in any detail for ~week, FTR.

[idontgetoutmuch]

I think using latex / mathjax syntax makes it easier for authors. I think most people would write the mathematics in another document e.g. a tex file and would want to cut and paste without having to re-format. Here's an example of what I mean. I can take this out of an existing document and put it straight into the proposed haddock (with each line being prefixed by "-- "). Ok I'd have to reformat the bold font but apart from that my job as an author is pretty straightforward. I think there is also a benefit to sticking to an existing convention rather than inventing our own.

Recall that a {\bf{transition kernel}} is a mapping \(\mu : X \times
{\cal{Y}} \rightarrow \overline{\mathbb{R}}_{+}\) where \((X,
{\cal{X}})\) and \((Y, {\cal{Y}})\)are two measurable spaces such that
\(\mu(s, \cdot)\) is a probability measure on \({\cal{Y}}\) for all
\(s \in X\) and such that \(\mu(\cdot, A)\) is a measurable function
on \(X\) for all \(A \in {\cal{Y}}\).

For example, we could have \(X = Y = \{a, b\}\) and \({\cal{X}} =
{\cal{Y}} = \{\emptyset, \{a\}, \{b\}, \{a,b\}\}\) and \(\mu(a,\{a\}) =
0.4, \mu(a,\{b\}) = 0.6, \mu(b,\{a\}) = 0.6, \mu(b,\{b\}) =
0.4\). Hopefully this should remind you of the transition matrix of a
Markov chain.

Recall further that a family of such transitions \(\{\mu_t\}_{t \in T}\)
where \(T\) is some index set satisfying

\[
\mu_{t+s}(x, A) = \int_{Y} \mu_s(x, {\mathrm{d}y})\mu_t(y, A)
\]

which is rendered via pdflatex as

[idontgetoutmuch]

You can now say

haddock --mathjax=file:///Users/whatever/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML

I can add a section to the haddock documentation itself if everyone is happy with this PR.

[Fuuzetsu]

Left a few comments. You should aim to squash some of the spurious commits you have as they serve no purpose on their own and save git tree clutter.

[idontgetoutmuch]

Thanks.

1. I just emailed Neil. He has responded "Sounds good to me" so I will remove the FIXME.
2. I think restricting inline maths to be on one line is reasonable. You tend to use it where you want to put a small number of symbols in some running text. If you want to run things over several lines then you can use display maths.

[Fuuzetsu]

Been looking at this so it may potentially go into 2.16.1. You don't seem to have updated the InterfaceFile.hs as a warning during compilation helpfully points out. That bit is kind of important or we end up losing the maths the moment multiple packages are involved. It's probably too late for 2.16.1 (due to be out with 7.10.2 which is due into RC very soon; my fault for being so tardy but that's how it is) but we may release another version later (which breaks interface file too, woo) independently or if 7.10.3 is happening then with that. We have a GSOC student doing some stuff for us so a bigger release will probably be in order anyway.

Branch also needs cleaning a bit (don't really need 5 fixup commits) and rebasing on master (1 new test added since that needs updating). I did these things to a basic degree at https://github.com/Fuuzetsu/haddock/tree/mathjax-merge if you want a reference.

[idontgetoutmuch]

I have some time today so I will try my best.

[idontgetoutmuch]

Ok I have squashed the commits but the required instances in InterfaceFile.hs seem to be generated by DrIFT. I don't know how to invoke DrIFT to do the necessary.

The only DrIFT directive I can find is

{-! for DocOption derive: Binary !-}

so it's not clear to me what I should do to generate Binary instances for DocH as there seems to be no directive for it.

Weirdly I can see a Binary instance for DocOption but it doesn't appear to have been generated by DrIFT.

Presumably we should get rid of any mention of DrIFT as I don't think it is actually used. I can add the instances by hand or we could use DeriveGeneric. Easiest is just to add the instances by hand which is what I will do for the PR. I will however delete mention of DrIFT as it just currently serves to confuse.

[Fuuzetsu]

Just pointing out that this PR has not been forgotten nor is being rejected. I am delaying it due to interface file changes required are an ugly update. But it only adds to the end of the structure (rather than changing existing types) so maybe it won't be too bad. I may include it in the next release which I hope comes fairly soon, including changes from GSOC.

@idontgetoutmuch

You can ignore the DrIFT comment as you did, I think it's just a very old mechanism that generated instances for you. Should just remove the comment.

[idontgetoutmuch]

Thanks for keeping me updated. I removed the reference to DrIFT already I think.

[Fuuzetsu]

That's great. We're keeping this PR on hold due to interface change, I want to see if I can't bundle some other similar changes with it instead of breaking things twice. So it may be a bit still before I merge and release it.

[idontgetoutmuch]

@Fuuzetsu any news on this? Will you make a release coincide with gcc 8? That would be in January I think?

[bgamari]

@idontgetoutmuch I don't mind merging this for GHC 8.0. Perhaps you could rebase on my ghc-head branch?

[idontgetoutmuch]

Ok I'll try my best - my git skills are not great.

@bgamari: Done. The build fails because it seems to be looking for haddock-api-2.16.2 but I am guessing this only exists for ghc 8 which the build system does not use?

[recursion-ninja]

Very excited, will begin using the feature as soon as it is released!

[bgamari]

This has been merged in #465!