Set up jsMath extensions, macros, etc., for the documentation

[qed777]

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

• attachment: trac_6673-jsmath_macros_docs_v3.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.

CC: @haraldschilly

Component: documentation

Author: Mitesh Patel

Reviewer: John Palmieri

Merged: sage-4.2.1.alpha0

Issue created by migration from https://trac.sagemath.org/ticket/6673

[qed777]

Depends on #6614.

[qed777]

comment:1

Attachment: trac_6673-jsmath_macros_docs.patch.gz

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

[jhpalmieri]

Reviewer: John Palmieri

[jhpalmieri]

comment:2

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:
    # used when building latex and pdf versions
    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.

[jhpalmieri]

Attachment: trac_6673-referee.patch.gz

apply on top of the other patch

[qed777]

comment:3

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.

[qed777]

comment:4

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

[jhpalmieri]

comment:5

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

[qed777]

comment:6

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.

[qed777]

Attachment: trac_6673-jsmath_macros_docs_v2.patch.gz

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

[qed777]

comment:7

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

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

[jhpalmieri]

comment:8

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

[jhpalmieri]

comment:9

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

[qed777]

comment:10

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.

[qed777]

comment:11

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

[qed777]

Attachment: trac_6673-jsmath_macros_docs_v3.patch.gz

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

[qed777]

comment:13

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 issue building sage docs since notebook moved #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.

[jhpalmieri]

comment:15

The code looks good. I've played around with it for a while, and it seems to do what it's supposed to.

Now schilly can get to work modifying "theme.conf" to produce a custom Sage theme...

[jhpalmieri]

comment:16

To the release manager: when merging this, please close #7204 also, since this resolves the problem reported there.

[mwhansen]

Merged: sage-4.2.1.alpha0