-
-
Notifications
You must be signed in to change notification settings - Fork 4.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
allow the notebook to run without MathJax #1077
Conversation
* 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 ipython#1071
if (window.MathJax == undefined){ | ||
// MathJax undefined, but expected. Draw warning. | ||
window.MathJax = null; | ||
var dialog = $('<div></div>').html( |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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:
- A user has not installed MathJax locally and the CDN could not be reached.
- 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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
* use jQuery syntax to construct dialog * server determines where MathJax comes from via mathjax_url configurable (default local/CDN priority unchanged)
Some comments addressed:
|
It's now more clear that offline mathjax info is server-related.
server-specific clarification added to failed mathjax dialog |
New text looks good. From where I see it, this can go in, thanks! |
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
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 ipython#1071
--no-mathjax
flag (and correspondingNotebookApp.enable_mathjax
configurable)for disabling mathjax in the notebook servercloses #1071