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

42 views
Skip to first unread message

John H Palmieri

unread,
Jun 20, 2012, 12:29:45 AM6/20/12
to sage-...@googlegroups.com
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
> sage-devel+...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/sage-devel
> URL: http://www.sagemath.org



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

Florent Hivert

unread,
Jun 20, 2012, 2:58:49 AM6/20/12
to sage-...@googlegroups.com
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

unread,
Jun 20, 2012, 4:24:51 AM6/20/12
to sage-...@googlegroups.com
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
instead?

-Keshav

Dima Pasechnik

unread,
Jun 20, 2012, 5:02:47 AM6/20/12
to sage-...@googlegroups.com
+1

jsMath is old (and unsupported upstream, IMHO).
 

-Keshav

Message has been deleted

John H Palmieri

unread,
Jun 20, 2012, 10:48:35 AM6/20/12
to sage-...@googlegroups.com


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

unread,
Jun 20, 2012, 11:38:01 AM6/20/12
to sage-...@googlegroups.com
sure, let's make it jsMath now and MathJax ASAP.
 

--
John

Jason Grout

unread,
Jun 20, 2012, 11:42:42 AM6/20/12
to sage-...@googlegroups.com
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

unread,
Jun 20, 2012, 12:25:21 PM6/20/12
to sage-...@googlegroups.com


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

unread,
Jun 20, 2012, 1:37:43 PM6/20/12
to sage-...@googlegroups.com


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

unread,
Jun 20, 2012, 1:42:40 PM6/20/12
to sage-...@googlegroups.com
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

unread,
Jun 20, 2012, 3:33:57 PM6/20/12
to sage-...@googlegroups.com

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

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

Jason

John H Palmieri

unread,
Jun 20, 2012, 4:10:39 PM6/20/12
to sage-...@googlegroups.com

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

unread,
Jun 20, 2012, 4:29:00 PM6/20/12
to sage-...@googlegroups.com
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.
>

Okay, that sounds about right.

Jason

John H Palmieri

unread,
Jun 20, 2012, 6:10:35 PM6/20/12
to sage-...@googlegroups.com


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

Reply all
Reply to author
Forward
0 new messages