Opened 12 years ago
Closed 12 years ago
#6673 closed defect (fixed)
Set up jsMath extensions, macros, etc., for the documentation
Reported by: | mpatel | Owned by: | tba |
---|---|---|---|
Priority: | major | Milestone: | sage-4.2.1 |
Component: | documentation | Keywords: | |
Cc: | schilly | Merged in: | sage-4.2.1.alpha0 |
Authors: | Mitesh Patel | Reviewers: | John Palmieri |
Report Upstream: | Work issues: | ||
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description (last modified by )
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.
Attachments (4)
Change History (21)
Changed 12 years ago by
comment:1 Changed 12 years ago by
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
- 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.
comment:3 Changed 12 years ago by
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
tojsmath_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
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
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
The forthcoming alternative patch inserts macros on-the-fly. It
- Moves
jsmath_sage.js
tojsmath_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 stringsage_jsmath_macros_jinja
inlatex_macros.py
. - Includes the string in a command-line option to Sphinx, in
builder.py
[1]. - Adds a trailing semcolon ("
;
") inlatex_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.
comment:7 Changed 12 years ago by
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
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
(Although \trianglelefteq should be available through the amssymbols package. Hmm.)
comment:10 Changed 12 years ago by
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
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
- 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
comment:13 Changed 12 years ago by
- 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
toMANIFEST.in
. - Leaves alone the now empty
SAGE_DOC/templates
andSAGE_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
- Description modified (diff)
comment:15 Changed 12 years ago by
- Status changed from needs_review to positive_review
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...
comment:16 Changed 12 years ago by
To the release manager: when merging this, please close #7204 also, since this resolves the problem reported there.
comment:17 Changed 12 years ago by
- Merged in set to sage-4.2.1.alpha0
- Resolution set to fixed
- Status changed from positive_review to closed
Depends on #6614.