\(\tiny \lim_{h\to 0} \frac{f(x + h) - f(x)}{h} \) Writing Math: MathJax and Desire2Learn \(\tiny \sum_{k=1}^{\infty} a_k / k!\)

Desire2Learn HTML Editor

Desire2Learn, the University of Waterloo course management computer system named LEARN, includes an HTML editor for creating online documents.

The HTML editor is used to make both whole html pages and blocks of html for inclusion in the systems many tools: forum posts, blog posts, quiz and survey questions, news announcements, and email.

The html editor includes three different ways to enter mathematics notation:

• a GUI pallet of mathematics symbols,
• mathml tags,
• mathematics LaTeX expressions.

The GUI mathematics input method is the simplest one for users new to writing mathematics online. Mathematics symbols are inserted into html text by clicking math symbol buttons.

MathML tags are not usually written by hand. The tag notation is too difficult to read and write. MathML tags are created by a separate mathematics editor or program that can export mathematics notation to MathML format. (See MathML notation at Wikipedia for more information.)

LaTeX mathematics notation is a well-established method of writing mathematics in many science fields. It uses a large vocabulary of command words for representing mathematics symbols and mathematics structures like matrices and numbered equations. (See LaTeX notation at Wikipedia for examples.)

The software that Desire2Learn's html editor uses for accepting input in LaTeX format is called MathJax. This javascript program is an open-source project with roots in the AsciiMATH program, another open-source project.

MathJax

MathJax translates mathematics expressions written in LaTeX or in a simpler, common mathematics text notation called AsciiMATH syntax into MathML expressions that are understood and rendered by most modern browsers. Browser Internet Explorer is the exception. It needs a plugin called MathPlayer to display MathML.

For browsers that cannot display MathML at all, Mathjax translates mathematics expressions into mathematics notation using HTML-CSS web fonts that is as good looking as MathML. MathJax is the math plugin of choice for blog, wiki and other online systems.

Using MathJax in a web page is simple. Here are two examples using both the LaTeX and AsciiMATH notations. Notice that regular text and math can mix easily on the same line (called inline math). Math can also be centered alone on a line (called display math).

 HTML AsciiMATH input:

<script type="text/javascript"
  // - place this script tag in the HTML Head section
  // - tex, mathml, and asciimath input; html or mathml output
  src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_HTMLorMML">
</script>

<p>
When `a != 0`, there are two solutions to `ax^2 + bx + c = 0` and they are
</p>
<p style="text-align:center">
`x = (-b +- sqrt(b^2-4ac))/(2a) .`
</p>

 HTML LaTeX input:

<script type="text/javascript"
  // - place this script tag in the HTML Head section
  // - tex, mathml, and asciimath input; html or mathml output
  src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_HTMLorMML">
</script>

<p>
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$</p>

Using MathJax in the Desire2Learn HTML Equation Editor

Either of the two examples above can be used when creating full HTML pages in Desire2Learn. The script tag in the examples has to be placed in the Head section of the HTML page, however.

Creating HTML blocks in the Desire2Learn tools, like forums and news announcements, the html editor does not allow access to the Head section of the html page because the user is only creating a small portion of a larger html page that the system will present. Thus, a user cannot call MathJax directly. Even using the MathJax inline script, which can call MathJax to perform its translation from within the body of an html page, will not work in Desire2Learn because all script tags created in the editor are made into unexecuted comments.

Instead, the HTML editor has an "Insert Equation" feature - a button which when clicked opens up a window where either LaTeX mathematics text or MathML text can be inserted. The following images show the equation editor window and the HTML editor window after inserting a math expression.

Equation editor

HTML editor

This implementation (in versions 9 and 10) has several limitations. First, only a single math expression can be inserted into the equation editor. MathJax can handle a mixed line of html and math text, named an inline math line, but the equation editor cannot. This means each inline math line will have to be split up into math expressions and html text and the equation editor used for each math expression in the line, breaking one of the nicest features of LaTeX and MathJax, that of freely composing math and text together on a line.

The second limitation is the HTML editor view of equations. While the equation editor shows the math expression as math, the HTML editor shows each math expression as a large, empty box, as shown in the above image on the right. The math content of the HTML editor window cannot be seen when it includes math expressions. When the HTML editor contents are saved, the math and regular html text are displayed correctly. But to edit the content, the math expressions will either have to be remembered or, more likely, the user will have to move back and forth between displaying, editing and saving operations instead of staying in the editor to make changes.

Another related drawback with working with only one math expression at a time is that those MathJax extensions which need loading e.g. the \xcancel command: \(\require{cancel} \xcancel{x+y^{21}}\), have to be loaded each time they are used with a math expression, instead of just once for the whole web page with MathJax.

Finally, all these limitations could be eliminated if the implementation of MathJax in Desire2Learn followed the usual plugin method for using MathJax i.e. include a javascript link to the MathJax library in the head section of course HTML pages in Desire2Learn, similar to the first html code example on this page, but using a Desire2Learn hosted version of MathJax instead. Oddly, the UW Desire2Learn implementation does have such a script tag but this script does not function. It is hoped that Desire2Learn will address the issue in a future edition of their software.

 Current D2L HTML:

<head>
<script type="text/javascript" src="/d2l/common/mathjax/2.0/MathJax.js?config=MML_HTMLorMML,
/d2l/lp/math/display/config.js?v=9.4.1000.112-7"></script>
</head>

Miscellaneous MathJax examples:

 HTML LaTeX input:

\begin{equation}
\left[
{\bf X} + {\rm a} \ \geq\
\underline{\hat a} \sum_i^N \lim_{x \rightarrow k} \delta C
\right]
\end{equation}

 HTML LaTeX input:

The \emph{characteristic polynomial} \(\chi(\lambda)\) of the
\(3 \times 3\)~matrix
\[ \left( \begin{array}{ccc}
a & b & c \\
d & e & f \\
g & h & i \end{array} \right)\] 
is given by the formula
\[ \chi(\lambda) = \left| \begin{array}{ccc}
\lambda - a & -b & -c \\
-d & \lambda - e & -f \\
-g & -h & \lambda - i \end{array} \right|.\] 

 HTML AsciiMATH input:

<p>
`a in A,  A subsetof B,  C supersetof D` and sets `NN, ZZ, and RR` 
</p>

MathJax tips

Read the Getting Started page to learn how to include MathJax math on your HTML pages. The support page is also a good reference for beginners and worth a read before dipping into the full documentation pages.

MathJax recreates LaTeX math expressions, not LaTeX text formatting, as seen in the second-to-last example above which uses the LaTeX command \emph{characteristic polynomial} which is not a math mode command and so is not translated by MathJax.

The current version 2 of MathJax allows defining LaTex macros and has optional automatic equation numbering. It also includes the \label macro for manual equation numbering and the \ref macro for referencing equations by number or label. See more options and extension on the MathJax TeX and LaTeX Support page.

• the usual LaTeX inline math mode $ delimiter is not used by default (but is an option); \ ( and \ ) is the safer default to use within html text
• put spaces around < and > symbols so the browser does not see them as html tags; or use the HTML entities &lt;, &gt; and &amp; instead; or use \lt and \gt mathjax defined macros
• put user macro definitions inside latex math mode delimiters \ (, \ ) or define macros in the mathjax config section using javascript object syntax -- see the RR: "{\ \bf R}" example
• macro definitions can use LaTeX commands \def, \newcommand, \renewcommand, \newenvironment, \renewenvironment, and \let
• mathjax 2 can do equation numbering, but it has to be turned on and has a few options (see autoNumber options):
  • always number equations,
  • number equations as in the AMS math environment eg turn off numbering with * in environment block
  • manual numbering using \nonumber or \notag (and see \label, \ref too)
• keep in mind that the browser interprets the text before MathJax does
• mathjax supports mathml 3.0 but some tags are not fully supported yet; see Supported MathML command section"
• math expressions can be scaled and colored using normal html methods

Paul Kates
Mathematics Faculty CTE Liaison
pkates@uwaterloo.ca, x37047