Opened 12 years ago

Last modified 12 years ago

#6673 closed defect

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

Reported by: mpatel Owned by: tba
Priority: major Milestone: sage-4.2.1
Component: documentation Keywords:
Cc: schilly Merged in:
Authors: Mitesh Patel Reviewers: John Palmieri
Report Upstream: Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by mpatel)

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.

Change History (18)

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:
    # 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.

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

  • Cc schilly added
  • 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.