Opened 12 years ago

Closed 11 years ago

Last modified 11 years ago

#6614 closed defect (fixed)

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

Reported by: mpatel Owned by: tba
Priority: minor Milestone: sage-4.1.2
Component: documentation Keywords:
Cc: rlm Merged in: Sage 4.1.2.alpha0
Authors: Mitesh Patel Reviewers: John Palmieri
Report Upstream: Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

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).

Attachments (3)

trac_6614-distutils_symlinks.patch (5.5 KB) - added by mpatel 12 years ago.
trac_6614-jsmath_repo.patch (1.2 MB) - added by mpatel 11 years ago.
Different approach.
trac_6614-jsmath_repo_v2.patch (1.2 MB) - added by mpatel 11 years ago.
New version that puts jsMath path first.

Change History (17)

Changed 12 years ago by mpatel

comment:1 Changed 12 years ago by mpatel

  • Cc rlm added
  • Component changed from algebra to documentation
  • Owner changed from tbd to tba
  • Priority changed from major to minor

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.

comment:2 Changed 12 years ago by jhpalmieri

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

Changed 11 years ago by mpatel

Different approach.

comment:3 follow-ups: Changed 11 years ago by 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.

Changed 11 years ago by mpatel

New version that puts jsMath path first.

comment:4 Changed 11 years ago by mpatel

  • Summary changed from Remove jsMath from version control in the Sage library. to [with patch, needs review] Remove jsMath from version control in the Sage library.

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.

comment:5 Changed 11 years ago by 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.

comment:6 in reply to: ↑ 3 Changed 11 years ago by 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.

comment:7 in reply to: ↑ 3 Changed 11 years ago by jhpalmieri

  • Authors set to Mitesh Patel
  • Milestone set to sage-4.1.2
  • Reviewers set to John Palmieri
  • Summary changed from [with patch, needs review] Remove jsMath from version control in the Sage library. to [with patch, positive review] Remove jsMath from version control in the Sage library.

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.

comment:8 Changed 11 years ago by 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.

comment:9 Changed 11 years ago by jhpalmieri

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

comment:10 Changed 11 years ago by mvngu

  • Merged in set to Sage 4.1.2.alpha0
  • Resolution set to fixed
  • Status changed from new to closed

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.

comment:11 Changed 11 years ago by mvngu

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

comment:12 Changed 11 years ago by 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.

comment:13 Changed 11 years ago by 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.

comment:14 Changed 11 years ago by 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?

Note: See TracTickets for help on using tickets.