[Docutils-checkins] SF.net SVN: docutils:[8115] trunk/docutils

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 8115
          http://sourceforge.net/p/docutils/code/8115
Author:   milde
Date:     2017-06-16 20:50:47 +0000 (Fri, 16 Jun 2017)
Log Message:
-----------
Fix [ 319 ] MathJax CDN shut down on April 30, 2017. 

For security reasons, we do not use a third party public installation as
default. Instead, if warn if math-output_ is set to MathJax without URL
and use a local MathJax installation on the client machine as fallback.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docs/user/config.txt
    trunk/docutils/docutils/writers/_html_base.py
    trunk/docutils/test/functional/expected/math_output_mathjax.html
    trunk/docutils/test/functional/tests/math_output_mathjax.py
    trunk/docutils/test/test_writers/test_html4css1_misc.py
    trunk/docutils/test/test_writers/test_html5_polyglot_misc.py

Modified: trunk/docutils/HISTORY.txt
===================================================================

--- trunk/docutils/HISTORY.txt	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/HISTORY.txt	2017-06-16 20:50:47 UTC (rev 8115)
@@ -14,7 +14,7 @@
 .. contents::
 
 
-Prerelease 0.14rc1 (2017-05-27)
+Prerelease 0.14rc2
 ===============================
 
 * docs/ref/docutils.dtd:
@@ -75,6 +75,9 @@
 
   - Provide default title in metadata (required by HTML5).
   - Fix [ 312 ] HTML writer generates invalid HTML if the table has two tags.
+  - Fix [ 319 ] The MathJax CDN shut down on April 30, 2017. For security
+    reasons, we don't use a third party public installation as default but
+    warn if math-output_ is set to MathJax without URL.
 
 * docutils/writers/html4css1/__init__.py
 
@@ -86,7 +89,7 @@
     in a "DUclass" environment. This replaces the special handling for
     "epigraph" and "topic" elements.
 
-* docutils/writers/odf_ odt/__init__.py:
+* docutils/writers/odf_odt/__init__.py:
 
   - Command setting ``language`` now sets the default language
     of the generated ODF document.

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/RELEASE-NOTES.txt	2017-06-16 20:50:47 UTC (rev 8115)
@@ -40,7 +40,7 @@
 .. _rst2html.py: docs/user/tools.html#rst2html-py
 
 
-Prerelease 0.14rc1 (2017-05-27)
+Prerelease 0.14rc2
 ===============================
 
 * docutils/docs/ref/docutils.dtd:
@@ -52,21 +52,22 @@
   - Added functionality: escaped whitespace in URI contexts.
   - Consistent handling of all whitespace characters in inline markup
     recognition. (May break documents that relied on some whitespace
-    characters (NBSP, ...) not to be recognized as whitespace.)
+    characters (NBSP, ...) *not* to be recognized as whitespace.)
 
 * docutils/utils/smartquotes.py:
 
   - Update quote definitions for et, fi, fr, ro, sv, tr, uk.
   - Add quote definitions for hr, hsb, hu, lv, sh, sl, sr.
-  - Fix [ 313 ] Differentiate apostrophe from closing single quote
-    (if possible).
-  - Fix [ 317 ] Extra space inserted with French smartquotes.
+  - Differentiate apostrophe from closing single quote (if possible).
   - Add command line interface for stand-alone use (requires 2.7).
 
 * docutils/writers/_html_base:
 
   - Provide default title in metadata.
-  - Fix [ 312 ] HTML writer generates invalid HTML if the table has two tags.
+  - The MathJax CDN shut down on April 30, 2017. For security reasons, we
+    don't use a third party public installation as default but warn
+    if `math-output` is set to MathJax without specifying a URL.
+    See math-output_ for details.
 
 * docutils/writers/html4css1:
 
@@ -78,10 +79,10 @@
     in a "DUclass" environment. This replaces the special handling for
     "epigraph" and "topic" elements.
 
-* docutils/writers/odf_ odt:
+* docutils/writers/odf_odt:
 
   - Language option sets ODF document's default language
-  - Image width, scale, ... set image size in generated ODF. 
+  - Image width, scale, ... set image size in generated ODF.
 
 * tools/
 

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/docs/user/config.txt	2017-06-16 20:50:47 UTC (rev 8115)
@@ -990,13 +990,11 @@
   (i.e. if there is mathematical content in the document).
 
 :MathJax:
-  Format math for display with MathJax_, a JavaScript-based math
-  rendering engine that uses HTML/CSS, JavaScript, and unicode
-  fonts for high-quality typesetting that is scalable and prints
-  at full resolution.
+  Format math for display with MathJax_, a JavaScript-based math rendering
+  engine.
 
   Pro:
-    Works 'out of the box' across multiple browsers and platforms.
+    Works across multiple browsers and platforms.
 
     Large set of `supported LaTeX math commands and constructs`__
 
@@ -1003,17 +1001,42 @@
     __ http://docs.mathjax.org/en/latest/tex.html#supported-latex-commands
 
   Con:
-    Requires an Internet connection or a local MathJax
-    installation and configuration.
+    Rendering requires JavaScript and an Internet connection or local
+    MathJax installation.
 
-    Downloads JavaScript code from a third-party site.
+  A URL pointing to a MathJax library should be appended after whitespace.
+  A warning is given if this is missing.
 
-  A custom URI can be appended after whitespace,
-  for example a local installation ::
+  * It is recommended to install__ the MathJax library on the same
+    server as the rest of the deployed site files.
 
-    math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
+    __ http://docs.mathjax.org/en/latest/installation.html
 
+    Example: Install the library at the top level of the web
+    server’s hierarchy in the directory ``MathJax`` and set::
 
+      math-output: mathjax /MathJax/MathJax.js
+
+  * The easiest way to use MathJax is to link directly to a public
+    installation. In that case, there is no need to install MathJax locally.
+
+    Downside: Downloads JavaScript code from a third-party site --- opens
+    the door to cross-site scripting attacs!
+
+    Example: MathJax.org recommends ``cdnjs.cloudflare.com``::
+
+      math-output: mathjax
+                   https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js
+
+    See https://cdnjs.com/about and https://www.cloudflare.com/terms/ for
+    details and terms of use.
+
+  * Use a local MathJax installation on the *client* machine, e.g.::
+
+      math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
+
+    This is the fallback if no URL is specified.
+
 :MathML:
   Embed math content as presentational MathML_.
 
@@ -1027,31 +1050,28 @@
     subset of LaTeX syntax.
 
     With the "html4css1" writer, the resulting HTML document does
-    not validate, as there is no DTD for MathML + XHTML
-    Transitional. However, MathML-enabled browsers will render it
-    fine.
+    not validate, as there is no DTD for `MathML + XHTML Transitional`.
+    However, MathML-enabled browsers will render it fine.
 
-  An external converter can be appended after whitespace:
+  An external converter can be appended after whitespace, e.g.,
+  ``--math-output="MathML latexml"``:
 
-  * ``math-output: MathML blahtexml``
+  blahtexml_
+    Fast conversion, support for many symbols and environments, but no
+    "align" (or other equation-aligning) environment. (C++)
 
-    blahtexml_ (C++) Fast conversion, support for many symbols and
-    environments, but no "align" (or other equation-aligning) environment.
+  LaTeXML_
+    Comprehensive macro support but very slow. (Perl)
 
-  * ``--math-output=MathML latexml``.
+  TtM_
+    No "matrix", "align" and  "cases" environments. Support may be removed.
 
-    LaTeXML_ (Perl) Comprehensive macro support but very slow
-
-  * ``--math-output=MathML ttm``, support may be removed.
-
-    No "matrix", "align" and  "cases" environments.
-
 :LaTeX:
   Include literal LaTeX code.
 
   The failsave fallback.
 
-Default: "HTML math.css" (MathML for the xhtml11 writer).
+Default: "HTML math.css" (The `[html5 writer]`_ defaults to "MathML").
 Option: ``--math-output``.
 
 New in Docutils 0.8.
@@ -1062,7 +1082,7 @@
 .. _MathML: http://www.w3.org/TR/MathML/
 .. _blahtexml: http://gva.noekeon.org/blahtexml/
 .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
-.. _ttm: http://hutchinson.belmont.ma.us/tth/mml/
+.. _TtM: http://hutchinson.belmont.ma.us/tth/mml/
 
 option_limit
 ~~~~~~~~~~~~
@@ -1315,6 +1335,9 @@
 
 Different default for:
 
+`math_output`_
+  Default: "MathML"
+
 `stylesheet_path <stylesheet_path [html4css1 writer]_>`_:
   Default: "minimal.css,plain.css"
 

Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/docutils/writers/_html_base.py	2017-06-16 20:50:47 UTC (rev 8115)
@@ -94,7 +94,8 @@
 
 
 class HTMLTranslator(nodes.NodeVisitor):
-    """Generic Docutils to HTML translator.
+    """
+    Generic Docutils to HTML translator.
 
     See the `html4css1` and `html5_polyglot` writers for full featured
     HTML writers.
@@ -113,13 +114,13 @@
 
            def visit_field_list(self, node):
                if foo:
-                   self.body.append('<div class="foo">\n')
+                   self.body.append('<div class="foo">')
                html4css1.HTMLTranslator.visit_field_list(self, node)
 
            def depart_field_list(self, node):
                html4css1.HTMLTranslator.depart_field_list(self, node)
                if foo:
-                   self.body.append('</div>\n')
+                   self.body.append('</div>')
 
       c) Overwrite both, call the parent functions under the same
          conditions::
@@ -141,7 +142,7 @@
            def depart_field_list(self, node):
                html4css1.HTMLTranslator.depart_field_list(self, node)
                if 'rfc2822' in node['classes']:
-                   self.body.append('<hr />\n')
+                   self.body.append('<hr />')
 
       This way, changes in stack use will not bite you.
     """
@@ -158,13 +159,22 @@
 
     # Template for the MathJax script in the header:
     mathjax_script = '<script type="text/javascript" src="%s"></script>\n'
-    # The latest version of MathJax from the distributed server:
-    # avaliable to the public under the `MathJax CDN Terms of Service`__
-    # __http://www.mathjax.org/download/mathjax-cdn-terms-of-service/
-    # may be overwritten by custom URL appended to "mathjax"
-    mathjax_url = ('https://cdn.mathjax.org/mathjax/latest/MathJax.js?'
-                   'config=TeX-AMS_CHTML')
 
+    mathjax_url = 'file:/usr/share/javascript/mathjax/MathJax.js'
+    """
+    URL of the MathJax javascript library.
+
+    The MathJax library ought to be installed on the same
+    server as the rest of the deployed site files and specified
+    in the `math-output` setting appended to "mathjax".
+    See `Docutils Configuration`__.
+
+    __ http://docutils.sourceforge.net/docs/user/config.html#math-output
+
+    The fallback tries a local MathJax installation at
+    ``/usr/share/javascript/mathjax/MathJax.js``.
+    """
+
     stylesheet_link = '<link rel="stylesheet" href="%s" type="text/css" />\n'
     embedded_stylesheet = '<style type="text/css">\n\n%s\n</style>\n'
     words_and_spaces = re.compile(r'\S+| +|\n')
@@ -1099,8 +1109,15 @@
         if self.math_output in ('latex', 'mathjax'):
             math_code = self.encode(math_code)
         if self.math_output == 'mathjax' and not self.math_header:
-            if self.math_output_options:
+            try:
                 self.mathjax_url = self.math_output_options[0]
+            except IndexError:
+                self.document.reporter.warning('No MathJax URL specified, '
+                    'using local fallback (see config.html)')
+            # append configuration, if not already present in the URL:
+            # input LaTeX with AMS, output common HTML
+            if '?' not in self.mathjax_url:
+                self.mathjax_url += '?config=TeX-AMS_CHTML'
             self.math_header = [self.mathjax_script % self.mathjax_url]
         elif self.math_output == 'html':
             if self.math_output_options and not self.math_header:

Modified: trunk/docutils/test/functional/expected/math_output_mathjax.html
===================================================================
--- trunk/docutils/test/functional/expected/math_output_mathjax.html	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/test/functional/expected/math_output_mathjax.html	2017-06-16 20:50:47 UTC (rev 8115)
@@ -5,7 +5,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils 0.14rc2.dev: http://docutils.sourceforge.net/" />
 <title>Mathematics</title>
-<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_CHTML"></script>
+<script type="text/javascript" src="/usr/share/javascript/mathjax/MathJax.js?config=TeX-AMS_CHTML"></script>
 <link rel="stylesheet" href="../input/data/html4css1.css" type="text/css" />
 </head>
 <body>

Modified: trunk/docutils/test/functional/tests/math_output_mathjax.py
===================================================================
--- trunk/docutils/test/functional/tests/math_output_mathjax.py	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/test/functional/tests/math_output_mathjax.py	2017-06-16 20:50:47 UTC (rev 8115)
@@ -8,8 +8,7 @@
 writer_name = "html"
 
 # Settings
-settings_overrides['math_output'] = 'MathJax'
+settings_overrides['math_output'] = 'MathJax /usr/share/javascript/mathjax/MathJax.js'
 # local copy of default stylesheet:
-settings_overrides['stylesheet_path'] = ( 
+settings_overrides['stylesheet_path'] = (
     'functional/input/data/html4css1.css')
-    

Modified: trunk/docutils/test/test_writers/test_html4css1_misc.py
===================================================================
--- trunk/docutils/test/test_writers/test_html4css1_misc.py	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/test/test_writers/test_html4css1_misc.py	2017-06-16 20:50:47 UTC (rev 8115)
@@ -141,10 +141,9 @@
     which is open to change in future Docutils releases. """
 
     mathjax_script = '<script type="text/javascript" src="%s">'
-    default_mathjax_url = ('https://cdn.mathjax.org/mathjax/latest/MathJax.js'
+    default_mathjax_url = ('file:/usr/share/javascript/mathjax/MathJax.js'
                            '?config=TeX-AMS_CHTML')
-    custom_mathjax_url = ('file:///usr/share/javascript/mathjax/MathJax.js'
-                          '?config=TeX-AMS-MML_HTMLorMML')
+    custom_mathjax_url = ('/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML')
     data = ':math:`42`'
 
     def test_math_output_default(self):
@@ -158,6 +157,7 @@
         # Explicitly specifying math_output=MathJax, case insensitively
         # use default MathJax URL
         mysettings = {'_disable_config': True,
+                      'report_level': 3,
                       'math_output': 'MathJax'}
         head = core.publish_parts(self.data, writer_name='html4css1',
             settings_overrides=mysettings)['head']

Modified: trunk/docutils/test/test_writers/test_html5_polyglot_misc.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot_misc.py	2017-06-16 09:01:13 UTC (rev 8114)
+++ trunk/docutils/test/test_writers/test_html5_polyglot_misc.py	2017-06-16 20:50:47 UTC (rev 8115)
@@ -141,10 +141,9 @@
     which is open to change in future Docutils releases. """
 
     mathjax_script = '<script type="text/javascript" src="%s">'
-    default_mathjax_url = ('https://cdn.mathjax.org/mathjax/latest/MathJax.js'
+    default_mathjax_url = ('file:/usr/share/javascript/mathjax/MathJax.js'
                            '?config=TeX-AMS_CHTML')
-    custom_mathjax_url = ('file:///usr/share/javascript/mathjax/MathJax.js'
-                          '?config=TeX-AMS-MML_HTMLorMML')
+    custom_mathjax_url = ('/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML')
     data = ':math:`42`'
 
     def test_math_output_default(self):
@@ -158,6 +157,7 @@
         # Explicitly specifying math_output=MathJax, case insensitively
         # use default MathJax URL
         mysettings = {'_disable_config': True,
+                      'report_level': 3,
                       'math_output': 'MathJax'}
         head = core.publish_parts(self.data, writer_name='html5_polyglot',
             settings_overrides=mysettings)['head']

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



