ox-html: Use upstream MathJax CDN

* ox-html.el (org-html-mathjax-options): Add multlinewidth, autonumber, tagindent, font, linebreaks and tagside. Remove MathML. Change default indent to correspond to upstream default. Change default MathJax path to point to upstream CDN. (org-html--build-mathjax-config): Remove MathML-related parts. (org-html-mathjax-template): Simplifiy template. * org.texi (@LaTeX{} fragments), (Math formatting in HTML export): Reflect change in default CDN. * ORG-NEWS: Document changes.
2024-12-04 08:47:03 +00:00 · 2015-02-16 02:04:02 +01:00 · 2015-02-16 02:04:02 +01:00 · 8c54b254b1
commit 8c54b254b1
parent 1c5db20860
3 changed files with 123 additions and 103 deletions
--- a/doc/org.texi
+++ b/doc/org.texi
@ -10258,20 +10258,17 @@ format sub- and superscripts in a WYSIWYM way.
 Going beyond symbols and sub- and superscripts, a full formula language is
 needed.  Org mode can contain @LaTeX{} math fragments, and it supports ways
 to process these for several export back-ends.  When exporting to @LaTeX{},
-the code is obviously left as it is.  When exporting to HTML, Org can invoke
-the @uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in
-HTML export}) to process and display the math@footnote{If you plan to use
-this regularly or on pages with significant page views, you should install
-@file{MathJax} on your own server in order to limit the load of our server.}.
-It can also process the mathematical expressions into images that can be
-displayed in a browser (see @pxref{Previewing @LaTeX{} fragments}).
+the code is left as it is.  When exporting to HTML, Org can use either
+@uref{http://www.mathjax.org, MathJax} (@pxref{Math formatting in HTML
+export}) or transcode the math into images (see @pxref{Previewing @LaTeX{}
+fragments}).

@LaTeX{} fragments don't need any special marking at all.  The following
 snippets will be identified as @LaTeX{} source code:
@itemize @bullet
@item
-Environments of any kind@footnote{When @file{MathJax} is used, only the
-environments recognized by @file{MathJax} will be processed.  When
+Environments of any kind@footnote{When MathJax is used, only the
+environments recognized by MathJax will be processed.  When
@file{dvipng} program or @file{imagemagick} suite is used to create images,
 any @LaTeX{} environment will be handled.}.  The only requirement is that the
@code{\begin} statement appears on a new line, at the beginning of the line
@ -10307,7 +10304,7 @@ either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
@vindex org-export-with-latex
@LaTeX{} processing can be configured with the variable
@code{org-export-with-latex}.  The default setting is @code{t} which means
-@file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} back-ends.
+MathJax for HTML, and no processing for ASCII and @LaTeX{} back-ends.
 You can also set this variable on a per-file basis using one of these
 lines:

@ -11466,25 +11463,23 @@ You could use @code{http} addresses just as well.
@cindex imagemagick

@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
-different ways on HTML pages.  The default is to use the
-@uref{http://www.mathjax.org, MathJax system} which should work out of the
-box with Org mode installation because @uref{http://orgmode.org} serves
-@file{MathJax} for Org mode users for small applications and for testing
-purposes.  @b{If you plan to use this regularly or on pages with significant
-page views, you should install@footnote{Installation instructions can be
-found on the MathJax website, see
-@uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on
-your own server in order to limit the load of our server.}  To configure
-@file{MathJax}, use the variable @code{org-html-mathjax-options} or
-insert something like the following into the buffer:
+different ways on HTML pages.  The default is to use
+@uref{http://www.mathjax.org, MathJax} which should work out of the box with
+Org@footnote{By default Org loads MathJax from
+@uref{http://docs.mathjax.org/en/latest/start.html#using-the-mathjax-content-delivery-network-cdn,
+MathJax.org}.  A link to the terms of service of the MathJax CDN can be found
+in the docstring of @code{org-html-mathjax-options}.}.  Some MathJax display
+options can be configured via @code{org-html-mathjax-options}, or in the
+buffer.  For example, with the following settings,
+@smallexample
+#+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
+@end smallexample
+equation labels will be displayed on the left marign and equations will be
+five ems from the left margin.

-@example
-#+HTML_MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
-@end example
-
-@noindent See the docstring of the variable
-@code{org-html-mathjax-options} for the meaning of the parameters in
-this line.
+@noindent See the docstring of
+@code{org-html-mathjax-options} for all supported variables.  The MathJax
+template can be configure via @code{org-html-mathjax-template}.

 If you prefer, you can also request that @LaTeX{} fragments are processed
 into small images that will be inserted into the browser page.  Before the
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@ -114,6 +114,11 @@ would create invalid planning info.  This dangerous option is now
 removed.
 *** Removed option ~org-koma-letter-use-title~
 Use org-export-with-title instead.  See also below.
+*** Removed MathML-related options from ~org-html-mathjax-options~
+MathJax automatically chooses the best display technology based on the
+end-users browser.  You may force initial usage of MathML via
+~org-html-mathjax-template~ or by setting the ~path~ property of
+~org-html-mathjax-options~.
 ** New features
 *** Additional markup with =#+INCLUDE= keyword
 The content of the included file can now be optionally marked up, for
@ -213,7 +218,9 @@ It is now possible to supply and optional formatting argument to
 *** New option ~org-export-with-title~
 It is possible to suppress the title insertion with ~#+OPTIONS:
 title:nil~ or globally using the variable ~org-export-with-title~.
-
+*** New MathJax configuration options.
+Org uses the MathJax CDN by default.  See the manual and the docstring
+of ~org-html-mathjax-options~ for details.
 ** Miscellaneous
 *** Strip all meta data from ITEM special property
 ITEM special property does not contain TODO, priority or tags anymore.
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@ -1064,82 +1064,111 @@ See `format-time-string' for more information on its components."
 ;;;; Template :: Mathjax

 (defcustom org-html-mathjax-options
-  '((path  "http://orgmode.org/mathjax/MathJax.js")
+  '((path "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML" )
    (scale "100")
    (align "center")
-    (indent "2em")
-    (mathml nil))
+    (font "TeX")
+    (linebreaks "false")
+    (autonumber "AMS")
+    (indent "0em")
+    (multlinewidth "85%")
+    (tagindent ".8em")
+    (tagside "right"))
  "Options for MathJax setup.

-path        The path where to find MathJax
-scale       Scaling for the HTML-CSS backend, usually between 100 and 133
-align       How to align display math: left, center, or right
-indent      If align is not center, how far from the left/right side?
-mathml      Should a MathML player be used if available?
-            This is faster and reduces bandwidth use, but currently
-            sometimes has lower spacing quality.  Therefore, the default is
-            nil.  When browsers get better, this switch can be flipped.
+Alist of the following elements.  All values are strings.
+
+path          The path to MathJax.
+scale         Scaling with HTML-CSS, MathML and SVG output engines.
+align         How to align display math: left, center, or right.
+font          The font to use with HTML-CSS and SVG output.  As of MathJax 2.5
+              the following values are understood: \"TeX\", \"STIX-Web\",
+              \"Asana-Math\", \"Neo-Euler\", \"Gyre-Pagella\",
+              \"Gyre-Termes\", and \"Latin-Modern\".
+linebreaks    Let MathJax perform automatic linebreaks.  Valid values
+              are \"true\" and \"false\".
+indent        If align is not center, how far from the left/right side?
+              Valid values are \"left\" and \"right\"
+multlinewidth The width of the multline environment.
+autonumber    How to number equations.  Valid values are \"None\", 
+              \"all\" and \"AMS Math\".
+tagindent     The amount tags are indented.
+tagside       Which side to show tags/labels on.  Valid values are 
+              \"left\" and \"right\"

 You can also customize this for each buffer, using something like

-#+MATHJAX: scale:\"133\" align:\"right\" mathml:t path:\"/MathJax/\""
+#+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
+
+For further information about MathJax options, see the MathJax documentation:
+
+    http://docs.mathjax.org/
+
+Please note that by using the default CDN one must agree with
+MathJax CDN Terms of Service.
+
+    http://www.mathjax.org/mathjax-cdn-terms-of-service.html"
  :group 'org-export-html
  :type '(list :greedy t
-	      (list :tag "path   (the path from where to load MathJax.js)"
-		    (const :format "       " path) (string))
-	      (list :tag "scale  (scaling for the displayed math)"
-		    (const :format "       " scale) (string))
-	      (list :tag "align  (alignment of displayed equations)"
-		    (const :format "       " align) (string))
-	      (list :tag "indent (indentation with left or right alignment)"
-		    (const :format "       " indent) (string))
-	      (list :tag "mathml (should MathML display be used is possible)"
-		    (const :format "       " mathml) (boolean))))
+	       (list :tag "path   (the path from where to load MathJax.js)"
+		     (const :format "       " path) (string))
+	       (list :tag "scale  (scaling for the displayed math)"
+		     (const :format "       " scale) (string))
+	       (list :tag "align  (alignment of displayed equations)"
+		     (const :format "       " align) (string))
+	       (list :tag "font (used to display math)"
+	       	     (const :format "            " font)
+	       	     (choice (const "TeX")
+	       		     (const "STIX-Web")
+	       		     (const "Asana-Math")
+	       		     (const "Neo-Euler")
+	       		     (const "Gyre-Pagella")
+	       		     (const "Gyre-Termes")
+	       		     (const "Latin-Modern")))
+	       (list :tag "linebreaks (automatic line-breaking)"
+		     (const :format "      " linebreaks)
+		     (choice (const "true")
+			     (const "false")))
+	       (list :tag "autonumber (when should equations be numbered)"
+		     (const :format "      " autonumber)
+		     (choice (const "AMS")
+			     (const "None")
+			     (const "All")))
+	       (list :tag "indent (indentation with left or right alignment)"
+		     (const :format "       " indent) (string))
+	       (list :tag "multlinewidth (width to use for the multline environment)"
+		     (const :format "       " multlinewidth) (string))
+	       (list :tag "tagindent (the indentation of tags from left or right)"
+		     (const :format "     " tagindent) (string))
+	       (list :tag "tagside (location of tags)"
+		     (const :format "      " tagside)
+		     (choice (const "left")
+			     (const "right")))))

 (defcustom org-html-mathjax-template
-  "<script type=\"text/javascript\" src=\"%PATH\"></script>
-<script type=\"text/javascript\">
-<!--/*--><![CDATA[/*><!--*/
+  "<script type=\"text/x-mathjax-config\">
    MathJax.Hub.Config({
-        // Only one of the two following lines, depending on user settings
-        // First allows browser-native MathML display, second forces HTML/CSS
-        :MMLYES: config: [\"MMLorHTML.js\"], jax: [\"input/TeX\"],
-        :MMLNO: jax: [\"input/TeX\", \"output/HTML-CSS\"],
-        extensions: [\"tex2jax.js\",\"TeX/AMSmath.js\",\"TeX/AMSsymbols.js\",
-                     \"TeX/noUndefined.js\"],
-        tex2jax: {
-            inlineMath: [ [\"\\\\(\",\"\\\\)\"] ],
-            displayMath: [ ['$$','$$'], [\"\\\\[\",\"\\\\]\"], [\"\\\\begin{displaymath}\",\"\\\\end{displaymath}\"] ],
-            skipTags: [\"script\",\"noscript\",\"style\",\"textarea\",\"pre\",\"code\"],
-            ignoreClass: \"tex2jax_ignore\",
-            processEscapes: false,
-            processEnvironments: true,
-            preview: \"TeX\"
-        },
-        showProcessingMessages: true,
        displayAlign: \"%ALIGN\",
        displayIndent: \"%INDENT\",

-        \"HTML-CSS\": {
-             scale: %SCALE,
-             availableFonts: [\"STIX\",\"TeX\"],
-             preferredFont: \"TeX\",
-             webFont: \"TeX\",
-             imageFont: \"TeX\",
-             showMathMenu: true,
-        },
-        MMLorHTML: {
-             prefer: {
-                 MSIE:    \"MML\",
-                 Firefox: \"MML\",
-                 Opera:   \"HTML\",
-                 other:   \"HTML\"
+        \"HTML-CSS\": { scale: %SCALE,
+                        linebreaks: { automatic: \"%LINEBREAKS\" },
+                        webFont: \"%FONT\"
+                       },
+        SVG: {scale: %SCALE,
+              linebreaks: { automatic: \"%LINEBREAKS\" },
+              font: \"%FONT\"},
+        NativeMML: {scale: %SCALE},
+        TeX: { equationNumbers: {autoNumber: \"%AUTONUMBER\"},
+               MultLineWidth: \"%MULTLINEWIDTH\",
+               TagSide: \"%TAGSIDE\",
+               TagIndent: \"%TAGINDENT\"
             }
-        }
-    });
-/*]]>*///-->
-</script>"
-  "The MathJax setup for XHTML files."
+});
+</script>
+<script type=\"text/javascript\"
+        src=\"%PATH\"></script>"
+  "The MathJax template.  See also `org-html-mathjax-options'."
  :group 'org-export-html
  :type 'string)

@ -1679,7 +1708,7 @@ INFO is a plist used as a communication channel."
    (let ((template (plist-get info :html-mathjax-template))
 	  (options (plist-get info :html-mathjax-options))
 	  (in-buffer (or (plist-get info :html-mathjax) ""))
-	  name val (yes "   ") (no "// ") x)
+	  name val x)
      (mapc
       (lambda (e)
 	 (setq name (car e) val (nth 1 e))
@ -1687,20 +1716,9 @@ INFO is a plist used as a communication channel."
 	     (setq val (car (read-from-string
 			     (substring in-buffer (match-end 0))))))
 	 (if (not (stringp val)) (setq val (format "%s" val)))
-	 (if (string-match (concat "%" (upcase (symbol-name name))) template)
-	     (setq template (replace-match val t t template))))
+	 (while (string-match (concat "%" (upcase (symbol-name name))) template)
+	   (setq template (replace-match val t t template))))
       options)
-      (setq val (nth 1 (assq 'mathml options)))
-      (if (string-match (concat "\\<mathml:") in-buffer)
-	  (setq val (car (read-from-string
-			  (substring in-buffer (match-end 0))))))
-      ;; Exchange prefixes depending on mathml setting.
-      (if (not val) (setq x yes yes no no x))
-      ;; Replace cookies to turn on or off the config/jax lines.
-      (if (string-match ":MMLYES:" template)
-	  (setq template (replace-match yes t t template)))
-      (if (string-match ":MMLNO:" template)
-	  (setq template (replace-match no t t template)))
      ;; Return the modified template.
      (org-element-normalize-string template))))