[with patch, positive review] Remove jsMath from version control in the Sage library.

[mpatel]

After the merge of #5799, we have jsMath installed in two places: $SAGE_ROOT/local/notebook/javascript and $SAGE_DOC/common/static. Moreover, all of jsMath is under version control in the Sage library. However, the standard practice for Sage development is to keep most upstream spkg code out of Mercurial's reach.

In particular, we'll need to do unnecessary extra work when we upgrade to new upstream versions of jsMath or keep track of local customizations (cf. #4714).

[mpatel]

This patch​ alters setup.py so that distutils includes broken symbolic links as it builds a source distribution of the Sage library. Is this appropriate?

If so, I can add another patch that replaces the jsmath directory in $SAGE_DOC/common/static with a symlink and updates the repository accordingly (i.e., reverses the patch mentioned ​here).

One caveat is that Python's ​os module supports symbolic links only on Unix systems. If we need to avoid links altogether, we could instead copy jsMath to multiple locations from its own spkg-install script.

[jhpalmieri]

Should we add the jsmath directory to devel/sage/.hgignore?

[mpatel]

Different approach.

[mpatel]

This alternative patch​ deletes doc/common/static/jsmath and adds jsMath to doc/common/conf.py's list of html_static_paths.

Since Sphinx recursively copies the only the contents of the static paths, jsMath no longer gets its own directory in _static. I've changed jsmath_path to 'easy/load.js'.

If we take this approach, then I should update the "new_scripts" patch at #6187.

[mpatel]

New version that puts jsMath path first.

[mpatel]

The new version prepends jsMath's path to html_static_path, so that custom files copied subsequently from, e.g., doc/common/static, can override certain settings, at our option.

The same caveats apply.

[mpatel]

An aside on Firefox's security policy:

• Build the reference manual with --jsmath.
• Browse to the table of contents in FF 3.5.
• Open "The Steenrod algebra", say, in a new background tab by middle-clicking (or the equivalent).
• Switch to the new tab. Did jsMath process the page? Not for me.
• Switch back to the ToC tab and browse directly to the same topic. Did jsMath process the page? Yes for me.

I've tested this only on Linux. Opera and Chromium don't behave this way, so I don't think it's [entirely] jsMath's fault.

In any case, this happens whether or not I apply the patch above.

[mpatel]

Replying to mpatel:

This alternative patch​ deletes doc/common/static/jsmath and adds jsMath to doc/common/conf.py's list of html_static_paths.

It may be necessary to delete doc/common/static/jsmath manually, after applying the patch.

[jhpalmieri]

Replying to mpatel:

Since Sphinx recursively copies the only the contents of the static paths, jsMath no longer gets its own directory in _static. I've changed jsmath_path to 'easy/load.js'.

Also, since the jsMath files all begin with "jsMath", we don't have to worry about name clashes (except, I suppose, the names of the subdirectories of jsMath, but I hope this won't be an issue).

Anyway, it looks good to me. I did manually delete doc/common/static/jsmath, and the documentation build correctly, with or without the "--jsmath" switch, and jsMath was active when reading docs off-line and on. The patch is large, but almost all of it consists of deleting files in doc/common/static/jsmath; the only "interesting" part is at the very beginning, the changes to conf.py. The changes there look good, both the new stuff and tidying up the old stuff (using os.path.join instead of "+", for example).

I hope I'm not missing anything, but I think it gets a positive review. Apply only ​trac_6614-jsmath_repo_v2.patch.

[mpatel]

I left alone the following line in MANIFEST.in

recursive-include doc/common/static *

I assume this is OK, although it's somewhat more than we need just now.

[jhpalmieri]

Yes, I noticed that and decided it was okay to leave it.

[mvngu]

For Sage 4.1.1 with trac_6614-jsmath_repo_v2.patch, reference manual built with ./sage -docbuild --jsmath reference html:

• jsMath can't handle Sage's customized LaTeX macros for common rings such such \RR for the reals, \ZZ for the integers, \QQ for the rationals, \CC for complex numbers, and \GF(p) for the finite field of p elements. See this screenshot.

• At least with Firefox 3.5.2, jsMath doesn't render LaTeX-typeset maths expressions very well. See this screenshot.

These two issues are not specific to the patch. The same things happen without trac_6614-jsmath_repo_v2.patch being applied to Sage 4.1.1.

Merged only trac_6614-jsmath_repo_v2.patch.

[mvngu]

I also manually deleted the directory doc/common/static/jsmath.

[mpatel]

We're working on Sage-specific jsMath customizations for the documentation at #6673.

The screenshots appear to be missing, at least for me.

From the ​changelog for jsMath 3.6c:

* Worked around another problem with Firefox 3.5's single-origin policy for
  local files that would cause jsMath not to be able to load external
  components.

This may address the "aside" above, unless it's besides the aside's point.

[mvngu]

I forgot to add links to the screenshots. See ​this for the customized LaTeX macros, and ​this for jsMath issues with Firefox 3.5.2.

[mpatel]

#6673 should help with the macros, but please let us know if we've missed any.

On the other problem: If Firefox is running on Linux, are the ​updated fonts installed?