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

[John H Palmieri]

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]

On 6/19/12 11:29 PM, John H Palmieri wrote:
> [X] Yes, make jsMath the default when running 'make'.

Thanks,

Jason

[Benjamin Jones]

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]

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]

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]

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]

+1

jsMath is old (and unsupported upstream, IMHO).

 

-Keshav

[John H Palmieri]

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]

sure, let's make it jsMath now and MathJax ASAP.

 

--
John

[Jason Grout]

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]

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]

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]

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]

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]

The mathjax directory should only be about 10M. Can you check its size
just to make sure?

Jason

[John H Palmieri]

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]

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]

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