allow the notebook to run without MathJax #1077

Merged
merged 4 commits into from Dec 6, 2011

Conversation

Projects
None yet
3 participants
Owner

minrk commented Dec 1, 2011

  • add --no-mathjax flag (and corresponding NotebookApp.enable_mathjax configurable)for disabling mathjax in the notebook server
  • A jQuery dialog with our 'no mathjax' message will appear if mathjax is unavailable, but the notebook will be fully functional after dismissal.
  • Various calls to MathJax.Hub.typeset moved to Cell.typeset, which checks for MathJax existence and is a no-op without it.
  • also a tiny fix where read-only mode swallowed all keyboard events, rather than allowing them to have their regular effect (e.g refresh).

closes #1071

minrk added some commits Nov 30, 2011

@minrk minrk don't swallow regular key events in read-only mode 91d457e
@minrk minrk allow the notebook to run without MathJax
* add `--no-mathjax` flag for disabling mathjax in the notebook server
* A jQuery dialog with our 'no mathjax' message will appear if mathjax is unavailable, but the notebook will be fully functional after dismissal.
* Various calls to MathJax.Hub.typeset moved to Cell.typeset, which checks for MathJax existence and is a no-op without it.

closes #1071
ef48cc0

@ellisonbg ellisonbg and 1 other commented on an outdated diff Dec 1, 2011

IPython/frontend/html/notebook/static/js/notebookmain.js
@@ -12,16 +12,62 @@
$(document).ready(function () {
- MathJax.Hub.Config({
- tex2jax: {
- inlineMath: [ ['$','$'], ["\\(","\\)"] ],
- displayMath: [ ['$$','$$'], ["\\[","\\]"] ]
- },
- displayAlign: 'left', // Change this to 'center' to center equations.
- "HTML-CSS": {
- styles: {'.MathJax_Display': {"margin": 0}}
- }
- });
+ if (window.MathJax == undefined){
+ // MathJax undefined, but expected. Draw warning.
+ window.MathJax = null;
+ var dialog = $('<div></div>').html(
@ellisonbg

ellisonbg Dec 1, 2011

Owner

I have been trying to create dynamic content using JQuery's DOM functions rather that using block html in strings. Please convert this code to use that approach.

@ellisonbg

ellisonbg Dec 1, 2011

Owner

The decision to use MatJax or not is one that is answered by the server side configuration. As such, any messages related to this should be printed by the server, not the notebook. It is entirely possible that the user who runs the notebook server and makes the MathJax decision is a different person that runs the client in a browser. Showing server side details in the browser confuses these two roles. A simple dialog "MathJax is not available in this notebook" would suffice in the client side.

@minrk

minrk Dec 1, 2011

Owner

I have been trying to create dynamic content using JQuery's DOM functions rather that using block html in strings. Please convert this code to use that approach.

I forgot about that - multiline javascript is hideous, but I didn't see anything better. I'll do that.

The decision to use MatJax or not is one that is answered by the server side configuration. As such, any messages related to this should be printed by the server, not the notebook.

The server can't print messages that the browser couldn't find MathJax - it has no idea that this is the case.

It is entirely possible that the user who runs the notebook server and makes the MathJax decision is a different person that runs the client in a browser.

Sure.

Showing server side details in the browser confuses these two roles.

This isn't happening. The dialog only appears if the browser tries to fetch MathJax and fails.

A simple dialog "MathJax is not available in this notebook" would suffice in the client side.

So are you asking that I add a second dialog, to inform the user that mathjax is unavailable even if it is not expected? Or should I remove all the helpful 'how to get mathjax' information from the dialog, and use it in both cases? I can imagine that running without mathjax resulting in a dialog every time would be extremely annoying.

@ellisonbg

ellisonbg Dec 1, 2011

Owner

Sorry, I had missed that this dialog only displays when MathJax was expected but couldn't be loaded. IOW, the server has said "use MathJax" and as far as it is concerned MathJax should work. There are two reasons this failure mode should appear:

  1. A user has not installed MathJax locally and the CDN could not be reached.
  2. A user has installed MathJax, but neither it nor the CDN version could be loaded.

If I understand things correctly, the dialog as you have it now cover case 1. The problem is that if a notebook is running publicly on the internet, you may not want to install MathJax locally because of the bandwidth of serving those files each time. In contexts like this the user should just get a message stating that MathJax could not be loaded and that equations won't render properly. They should even be encouraged to reload the page at a later moment in time to see if the CDN comes back up. In this case, the user does have internet connectivity because they are able to contact the remote notebook server. I am not sure how to handle this case, but these users should not be shown the dialog about server configuration.

Option 2 is extremely rare because if the local MathJax won't load, then it is most likely that the notebook wouldn't have loaded at all.

There may be a better way of handling this...

What about having the server decide what URL should be used to load MathJax. That would enable the server to look and see if MathJax was installed locally (in which case the local URL would be loaded) or if the CDN URL should be used. The server could perform this test at startup and print a message about which version of MathJax would be used and warn users that an internet connection is required if the CDN version is used.

Then the browser side code is simplified greatly:

  • If MathJax is not enabled by the server, pass silently or possible just dialog the user "MathJax not enabled, equations won't render."
  • If MathJax doesn't load, we can provide a dialog that is matched to the way MathJax should have been loaded. If the CDN version should have been used, tell the user that an internet connection is required but is not working, etc. If the local version should have been used, then there is a more serious server error that would likely affect the entire notebook.

I have never liked it that the browser made the decision of where to load MathJax from and this would solve that problem. How does this sound? Am I missing anything?

@minrk

minrk Dec 1, 2011

Owner

Option 2 is extremely rare because if the local MathJax won't load, then it is most likely that the notebook wouldn't have loaded at all.

I agree, I don't think there is any point in handling this case.

What about having the server decide what URL should be used to load MathJax.

That makes sense, it eliminates the 404 we get on most normal notebook page requests.

Then the browser side code is simplified greatly

I think this is an exaggeration - it removes a 5-line javascript function and that's about it, but it is definitely cleaner. The only code that might actually be simplified is the dialog, and it's not clear to me what you are suggesting we say when mathjax failed to load.

By far the most likely case is that the notebook is unconfigured and local, and the user is running the notebook with no/slow internet connection. The most likely information that the user wants is either 'how can I use mathjax in offline mode' or 'how can I ignore mathjax, and disable this warning'. That's all the dialog covers.

This is the problem we are always running into with the notebook - it's not true in general that user/server are the same person and/or machine, but it is true 99% of the time. So should we never give server-admin relevant information to the browser? That seems like punishing users for design-cleanliness.

@ellisonbg ellisonbg and 1 other commented on an outdated diff Dec 1, 2011

IPython/frontend/html/notebook/static/js/notebookmain.js
@@ -12,16 +12,62 @@
$(document).ready(function () {
- MathJax.Hub.Config({
- tex2jax: {
- inlineMath: [ ['$','$'], ["\\(","\\)"] ],
- displayMath: [ ['$$','$$'], ["\\[","\\]"] ]
- },
- displayAlign: 'left', // Change this to 'center' to center equations.
- "HTML-CSS": {
- styles: {'.MathJax_Display': {"margin": 0}}
- }
- });
+ if (window.MathJax == undefined){
@ellisonbg

ellisonbg Dec 1, 2011

Owner

It also seems a bit verbose to show this dialog on the opening of every notebook. It seems like it should be shown to the user once, maybe when the notebook dashboard in opened?

@minrk

minrk Dec 1, 2011

Owner

I can do that, but it has two obvious disadvantages:

  • It would require loading MathJax on the dashboard purely to check if it can be loaded
  • It doesn't handle the case of loading the dashboard while you have a good internet connection, and loading a notebook after leaving the network, which will lack MathJax without any notification.
@minrk minrk adjust missing mathjax handling per review
* use jQuery syntax to construct dialog
* server determines where MathJax comes from via mathjax_url configurable (default local/CDN priority unchanged)
e211da8
Owner

minrk commented Dec 2, 2011

Some comments addressed:

  • use jQuery syntax to construct dialog
  • server determines where MathJax comes from via mathjax_url configurable (default local/CDN priority unchanged)
@minrk minrk add server/permission info in failed-mathjax dialog
It's now more clear that offline mathjax info is server-related.
8e5ff16
Owner

minrk commented Dec 5, 2011

server-specific clarification added to failed mathjax dialog

Owner

fperez commented Dec 6, 2011

New text looks good. From where I see it, this can go in, thanks!

@minrk minrk added a commit that referenced this pull request Dec 6, 2011

@minrk minrk Merge pull request #1077 from minrk/nb
allow the notebook to run without MathJax

adds --no-mathjax flag for disabling mathjax, and moves the mathjax URL decision to the server from the browser.

closes #1071
0040446

@minrk minrk merged commit 0040446 into ipython:master Dec 6, 2011

@mattvonrocketstein mattvonrocketstein pushed a commit to mattvonrocketstein/ipython that referenced this pull request Nov 3, 2014

@minrk minrk Merge pull request #1077 from minrk/nb
allow the notebook to run without MathJax

adds --no-mathjax flag for disabling mathjax, and moves the mathjax URL decision to the server from the browser.

closes #1071
32d042f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment