# Proposal: by default, at least in Makefile, build docs using jsMath

42 views

### John H Palmieri

Jun 20, 2012, 12:29:45 AM6/20/12
When you run 'make' in SAGE_ROOT, it builds sage and runs 'make doc-html'. I propose changing this so it instead runs 'make doc-html-jsmath', which uses jsMath to display math, rather than png images. In my experience, using jsMath is much faster, and the output looks good.  (Individual users can make this the default by setting the environment variable SAGE_DOC_JSMATH to "yes", by the way.)

[ ]  Yes, make jsMath the default when running 'make'.
[ ]  No, keep it as is.

-------

To compare the two, try this while in SAGE_ROOT:

$unset SAGE_DOC_JSMATH$ rm -rf devel/sage/doc/output
$time ./sage -docbuild tutorial html Now repeat the last two lines: sometimes the first run through is slower than the rest. You should note how long it takes, and also look at the output. Then do$ rm -rf devel/sage/doc/output
$time ./sage -docbuild tutorial html -j # "-j" says to use jsMath and compare output and timings. On my machine, without jsMath takes about 2 minutes, with jsMath takes about 10 seconds. We must have had some reason for not using jsMath by default. Does anyone remember what it was? -- John ### Jason Grout unread, Jun 20, 2012, 12:35:33 AM6/20/12 to sage-...@googlegroups.com On 6/19/12 11:29 PM, John H Palmieri wrote: > [X] Yes, make jsMath the default when running 'make'. Thanks, Jason ### Benjamin Jones unread, Jun 20, 2012, 12:52:53 AM6/20/12 to sage-...@googlegroups.com On Tue, Jun 19, 2012 at 11:29 PM, John H Palmieri <jhpalm...@gmail.com> wrote: > > [X] Yes, make jsMath the default when running 'make'. The difference is huge. I get (without -j) real 0m13.313s (average over 3 runs) (with -j) real 1m18.227s (average over 3 runs) -- Benjamin Jones ### William Stein unread, Jun 20, 2012, 1:44:44 AM6/20/12 to sage-...@googlegroups.com On Tue, Jun 19, 2012 at 9:29 PM, John H Palmieri <jhpalm...@gmail.com> wrote: > When you run 'make' in SAGE_ROOT, it builds sage and runs 'make doc-html'. I > propose changing this so it instead runs 'make doc-html-jsmath', which uses > jsMath to display math, rather than png images. In my experience, using > jsMath is much faster, and the output looks good. (Individual users can > make this the default by setting the environment variable SAGE_DOC_JSMATH to > "yes", by the way.) > [X] Yes, make jsMath the default when running 'make'. [ ] No, keep it as is. png's were always a temporary hack... Just one question though: what about MathJax versus jsMath for this discussion? Are they equivalent, or soon will be? -- William > > ------- > > To compare the two, try this while in SAGE_ROOT: > >$ unset SAGE_DOC_JSMATH
>
>    $rm -rf devel/sage/doc/output >$ time ./sage -docbuild tutorial html
>
> Now repeat the last two lines: sometimes the first run through is slower
> than the rest. You should note how long it takes, and also look at the
> output. Then do
>
>    $rm -rf devel/sage/doc/output >$ time ./sage -docbuild tutorial html -j  # "-j" says to use jsMath
>
> and compare output and timings. On my machine, without jsMath takes about 2
> minutes, with jsMath takes about 10 seconds.
>
> We must have had some reason for not using jsMath by default. Does anyone
> remember what it was?
>
> --
> John
>
> --
> To post to this group, send an email to sage-...@googlegroups.com
> To unsubscribe from this group, send an email to
> For more options, visit this group at
> URL: http://www.sagemath.org

--
William Stein
Professor of Mathematics
University of Washington
http://wstein.org

### Florent Hivert

Jun 20, 2012, 2:58:49 AM6/20/12
On Tue, Jun 19, 2012 at 09:29:45PM -0700, John H Palmieri wrote:
> When you run 'make' in SAGE_ROOT, it builds sage and runs 'make doc-html'.
> I propose changing this so it instead runs 'make doc-html-jsmath', which
> uses jsMath to display math, rather than png images. In my experience,
> using jsMath is much faster, and the output looks good. (Individual users
> can make this the default by setting the environment variable
> SAGE_DOC_JSMATH to "yes", by the way.)
>
> [X] Yes, make jsMath the default when running 'make'.

Florent

### Keshav Kini

Jun 20, 2012, 4:24:51 AM6/20/12
John H Palmieri <jhpalm...@gmail.com> writes:
> [ ] Yes, make jsMath the default when running 'make'.

Yes! But why not make the ticket depend on #9774 and use MathJax

-Keshav

### Dima Pasechnik

Jun 20, 2012, 5:02:47 AM6/20/12
+1

jsMath is old (and unsupported upstream, IMHO).

-Keshav

Message has been deleted

### John H Palmieri

Jun 20, 2012, 10:48:35 AM6/20/12

On Tuesday, June 19, 2012 10:44:44 PM UTC-7, William wrote:
On Tue, Jun 19, 2012 at 9:29 PM, John H Palmieri wrote:
> When you run 'make' in SAGE_ROOT, it builds sage and runs 'make doc-html'. I
> propose changing this so it instead runs 'make doc-html-jsmath', which uses
> jsMath to display math, rather than png images. In my experience, using
> jsMath is much faster, and the output looks good.  (Individual users can
> make this the default by setting the environment variable SAGE_DOC_JSMATH to
> "yes", by the way.)
>

[X]  Yes, make jsMath the default when running 'make'.
[ ]  No, keep it as is.

png's were always a temporary hack...   Just one question though: what
about MathJax versus jsMath for this discussion?  Are they equivalent,
or soon will be?

If we decide to use jsMath now in the Makefile, then because of the changes at #9774, when we switch to MathJax, it will be used automatically instead.

Keshav and Dima, note this also.

--
John

### Dima Pasechnik

Jun 20, 2012, 11:38:01 AM6/20/12
sure, let's make it jsMath now and MathJax ASAP.

--
John

### Jason Grout

Jun 20, 2012, 11:42:42 AM6/20/12
On 6/20/12 10:38 AM, Dima Pasechnik wrote:
> sure, let's make it jsMath now and MathJax ASAP.

The hope is that mathjax will be merged into 5.2, along with the new
notebook. Mathjax is already running on *.sagenb.org.

Jason

### P Purkayastha

Jun 20, 2012, 12:25:21 PM6/20/12

On Wednesday, June 20, 2012 12:29:45 PM UTC+8, John H Palmieri wrote:
When you run 'make' in SAGE_ROOT, it builds sage and runs 'make doc-html'. I propose changing this so it instead runs 'make doc-html-jsmath', which uses jsMath to display math, rather than png images. In my experience, using jsMath is much faster, and the output looks good.  (Individual users can make this the default by setting the environment variable SAGE_DOC_JSMATH to "yes", by the way.)
[X]  Yes, make jsMath the default when running 'make'.

[ ]  No, keep it as is.

Though I would prefer that it move to mathjax.

### John H Palmieri

Jun 20, 2012, 1:37:43 PM6/20/12

On Tuesday, June 19, 2012 9:29:45 PM UTC-7, John H Palmieri wrote:
When you run 'make' in SAGE_ROOT, it builds sage and runs 'make doc-html'. I propose changing this so it instead runs 'make doc-html-jsmath', which uses jsMath to display math, rather than png images. In my experience, using jsMath is much faster, and the output looks good.  (Individual users can make this the default by setting the environment variable SAGE_DOC_JSMATH to "yes", by the way.)

One advantage to *not* using jsMath: the docs using jsMath take about 500 megabytes, compared to about 300 without jsMath. I haven't checked with MathJax. (I still think it's worth using jsMath.)

--
John

### Jason Grout

Jun 20, 2012, 1:42:40 PM6/20/12
Is that because a copy of jsmath is copied over to the output directory?
MathJax will be a lot smaller (if we don't use the image fonts).

Jason

### John H Palmieri

Jun 20, 2012, 3:33:57 PM6/20/12

I think so.

MathJax will be a lot smaller (if we don't use the image fonts).

Ah, you're right: switching from jsMath to MathJax changes the disk space from 526M to 296M on my machine.

--
John

### Jason Grout

Jun 20, 2012, 3:49:52 PM6/20/12
The mathjax directory should only be about 10M. Can you check its size
just to make sure?

Jason

### John H Palmieri

Jun 20, 2012, 4:10:39 PM6/20/12

I'm not sure which mathjax directory you mean. In doc/output/...., there are directories like

doc/output/html/en/reference/_static/

containing a file "MathJax.js" and a directory "jax". Each of these _static directories (one for each component of the documentation, all identical, AFAIK) takes 5.5M on my machine.

--
John

### Jason Grout

Jun 20, 2012, 4:29:00 PM6/20/12
On 6/20/12 3:10 PM, John H Palmieri wrote:

> I'm not sure which mathjax directory you mean. In doc/output/...., there
> are directories like
>
> doc/output/html/en/reference/_static/
>
> containing a file "MathJax.js" and a directory "jax". Each of these
> _static directories (one for each component of the documentation, all
> identical, AFAIK) takes 5.5M on my machine.
>

Jason

### John H Palmieri

Jun 20, 2012, 6:10:35 PM6/20/12

On Tuesday, June 19, 2012 9:29:45 PM UTC-7, John H Palmieri wrote:
When you run 'make' in SAGE_ROOT, it builds sage and runs 'make doc-html'. I propose changing this so it instead runs 'make doc-html-jsmath', which uses jsMath to display math, rather than png images. In my experience, using jsMath is much faster, and the output looks good.  (Individual users can make this the default by setting the environment variable SAGE_DOC_JSMATH to "yes", by the way.)

[ ]  Yes, make jsMath the default when running 'make'.
[ ]  No, keep it as is.

The vote so far is overwhelmingly to switch to jsMath and/or MathJax. I've decided, after all, to make MathJax (#9774) a prerequisite for this, especially since #9774 is positively reviewed. See <http://trac.sagemath.org/sage_trac/ticket/13143>. It should be easy to review, once you've installed #9774.

I'll certainly keep an eye on this thread, and if people here express serious concerns about this switch, I will try to make sure they get recorded on the trac ticket.

--
John