[Python-modules-team] Bug#677929: python-docutils: remote copy of MathJax needed to render maths

[Guenter Milde]

> That is, if you open such document in a modern browser, it will happily 
> download some JavaScript code from a remote site. I feel this violation 
> of our users privacy (and a security concern).

This depends on the browser settings of the user. Users concerned for
privacy and security will have safeguards in place, because browsing the
internet without these safeguards almost inevitable means to download and
execute JavaScript from remote sites. With JavaScript blocked, the user
will see the latex source, instead of a rendering. 

I agree that a web page should not use javascript without need. However,
the idea with mathjax as default math-output-format is to have something
that works "out of the box" for most users - all alternatives are
currently not up to the task but require additional configuration. I
checked the mathjax site and it appeared to be a serious project by
serious players (see http://www.mathjax.org/sponsors/). 

This is why I do not agree with labeling this as a "serious" bug.

OTOH, a configurable the mathjax URL is a valid enhancement request. The
source contains the lines:

    mathjax_url = ('http://cdn.mathjax.org/mathjax/latest/MathJax.js?'
                   'config=TeX-AMS-MML_HTMLorMML')
    # TODO: make this configurable:
    #
    # a) as extra option or
    # b) appended to math-output="MathJax"?
    #
    # If b), which delimiter/delimter-set (':', ',', ' ')?

As a workaround, users can configure the MathJaX URL (be it for `using the
https protocoll`__, configuring__ the remote server or using a local server)
can do so with a custom rst2html front end: 

Copy ``rst2html`` to the local binary path and insert ::

  # customize the MathJaX URL:
  from docutils.writers import html4css1
  html4css1.HTMLTranslator.mathjax_url = 'my custom mathjax url'

just before the ``publish_cmdline ...`` call.

__ http://www.mathjax.org/docs/2.0/start.html#secure-access-to-the-cdn
__ http://www.mathjax.org/docs/2.0/configuration.html#loading



> The attached debdiff adds a "use-local-mathjax.diff" patch to
> debian/patches, and adds a dependency on libjs-mathjax package to both
> python-docutils and python3-docutils.

Please do not make libjs-mathjax a dependency (maybe a suggestion). Besides
adding a quite large requirements, it also does not help in the quite common
case where you generate documentation to upload to another site!

If defaulting to mathjax-remote is an issue, a global config file
/etc/docutils.conf could be used to set::

  # These entries affect HTML output:
  [html4css1 writer]
  math-output: HTML