Opened 12 years ago

# Set up jsMath extensions, macros, etc., for the documentation — at Version 14

Reported by: Owned by: mpatel tba major sage-4.2.1 documentation schilly Mitesh Patel John Palmieri

Currently, the documentation uses a stock jsMath loader script. This excludes Sage-specific customizations, e.g., the notebook's default jsMath macros. The patch

inserts the settings via a template when the docs are built. The patch also sets up a 'sage' HTML theme (cf. Sphinx docs) for later customization.

See #4714 for a "notebook" version.

### Changed 12 years ago by mpatel

Depends on #6614.

### comment:1 Changed 12 years ago by mpatel

Note: Depending on the outcome of this ticket, we may need to update the "scripts" patch at #6187.

### comment:2 Changed 12 years ago by jhpalmieri

• Milestone set to sage-4.1.2
• Reviewers set to John Palmieri

With the patch, commands like \ZZ in the docs appear correctly in the off-line (html+jsmath) version of the reference manual, the tutorial, etc.

Is there any way to generate the list of macros automatically, the way it is done in doc/common/conf.py for the LaTeX version:

for macro in sage_latex_macros:
latex_preamble += macro + '\n'
# used when building html version
pngmath_latex_preamble += macro + '\n'


I don't see anything helpful in the Sphinx documentation, unfortunately. So instead, I'm attaching a small patch to the file sage/misc/latex_macros.py, suggesting that if the list of macros there gets changed, the list in jsmath_sage.js must be changed also, and I've put a pointer to latex_macros.py in jsmath_sage.js.

For the file jsmath_sage.js, it looks like a modified version of easy/load.js, but it's not the same as the one distributed with Sage (the one in local/notebook/javascript/jsmath/easy); there are white space differences, and there are differences below the line saying "DO NOT MAKE CHANGES BELOW THIS". Do I need to worry about this? Let me know, and if it's not a problem, I can give this a positive review.

### Changed 12 years ago by jhpalmieri

apply on top of the other patch

### comment:3 Changed 12 years ago by mpatel

Rather inconveniently, I described the patch, briefly, in a comment at #4714. I apologize for not adding some information here.

With Sphinx 0.6.2 (cf. #6586), we might use static templates to insert the macros on-the-fly. A test:

• Move jsmath_sage.js to jsmath_sage.js_t
• Temporarily sandwich the macros: { } block between {% raw %} and {% endraw %} to placate Jinja.
• Add the comment // {{ foo }} somewhere.
• Run sage -docbuild testreference html -jv3 -S -Afoo=bar.

I find // bar in place of the "foo" statement in _static/jsmath_sage.js. In the next few days, I'll try to create a new ticket with a proper patch.

Since we're not there yet, I give the "referee" patch a positive review.

### comment:4 Changed 12 years ago by mpatel

I just noticed that jsMath complains about \mathfrak and \mod in

• doc/static/bordeaux_2008/integer_factorization.html
• doc/static/bordeaux_2008/modular_forms_and_hecke_operators.html
• doc/output/html/en/bordeaux_2008/modabvar.html

### comment:5 Changed 12 years ago by jhpalmieri

So the plan is to have this depend on #6586? (That's fine with me, I just want to make sure I understand.)

### comment:6 Changed 12 years ago by mpatel

The forthcoming alternative patch inserts macros on-the-fly. It

• Moves jsmath_sage.js to jsmath_sage.js_t and replaces the list of jsMath macros with a Jinja macro.
• Adds convert_to_latex_js_math_easy() to and generates the string sage_jsmath_macros_jinja in latex_macros.py.
• Includes the string in a command-line option to Sphinx, in builder.py [1].
• Adds a trailing semcolon (";") in latex_macros.convert_latex_macro_to_jsmath().

[1] It seems that we can override the templates' default html_context dictionary only on the command-line, i.e., with the -A option (cf. sphinx/config.py). This means that adding html_context = <the macros> in conf.py won't work.

### Changed 12 years ago by mpatel

Template version. Depends on #6187, #6586. Apply only this patch.

### comment:7 Changed 12 years ago by mpatel

I haven't added/fixed \mathfrak, \mod, or whatever is happening near the top of

• doc/static/reference/sage/modular/arithgroup/congroup_gammaH.html

### comment:8 Changed 12 years ago by jhpalmieri

Re congroup_gammaH.html, if it's the "\trianglelefteq", then I think it can safely be replaced with "\leq". (It's a subgroup of an abelian group, so it's automatically normal.)

### comment:9 Changed 12 years ago by jhpalmieri

(Although \trianglelefteq should be available through the amssymbols package. Hmm.)

### comment:10 Changed 12 years ago by mpatel

Should we add new macros in a separate ticket?

If so, I can try to set up #4714 to use the same sage_jsmath_macros_jinja as this ticket. But we can just call them sage_jsmath_macros, since we'll usually use just the template version. Of course, we can keep convert_latex_macro_to_jsmath for on-the-fly definitions.

### comment:11 Changed 12 years ago by mpatel

Also: How should we set up tex2math in jsmath_sage.js_t? Should we use the same settings for the notebook and docs?

### comment:12 Changed 12 years ago by mpatel

• Status changed from needs_review to needs_work
• Summary changed from [with patch, needs review] Set up jsMath extensions, macros, etc., for the documentation to Set up jsMath extensions, macros, etc., for the documentation

### Changed 12 years ago by mpatel

Updated template version. Added 'sage' theme. Apply only this patch.

### comment:13 Changed 12 years ago by mpatel

• Priority changed from minor to major
• Status changed from needs_work to needs_review

Version 3:

• Organizes a 'sage' theme for easier customization. See SAGE_DOC/themes/sage/theme.conf for the settings.
• Uses the theme to avoid passing jsMath macros on the command-line.
• Disables tex2math.
• Subsumes #7204. In particular, this depends on SageNB version 0.3.2 or later.
• Makes the Sage logo a link to the top-level doc page. For the doc page itself, the link is to SageMath.
• Adds SAGE_DOC/themes to MANIFEST.in.
• Leaves alone the now empty SAGE_DOC/templates and SAGE_DOC/static.

Remarks:

• We should add a friendly welcome message to the top-level doc page, e.g., near the top or in the sidebar.

### comment:14 Changed 12 years ago by mpatel

• Description modified (diff)
Note: See TracTickets for help on using tickets.