Mathematical Notation in Online R/exams

Many R/exams exercises employ mathematical notation that needs to be converted and rendered suitably for inclusion in online exams. While R/exams attempts to set suitable defaults, an overview is provided of possible adjustments and when these might be useful or even necessary.

Overview

A popular use case of the R/exams package is the generation of dynamic exercises for online learning management systems in large-scale courses in mathematics , statistics, or physics. Often, these contain some mathematical notation using LaTeX markup. While LaTeX can be easily rendered into PDF for printing written exams, the options for rendering it into HTML for online exams are somewhat more diverse and the best strategies depend on a number of factors. As these involve a number of technical details this tutorial aims to give a brief overview and makes a few practical recommendations. Factors include the following:

• Original markup in exercise source files:
  The R/exams exercises may employ either Markdown or LaTeX for formatting and structuring the text (see the First steps tutorial for more details). In either case LaTeX is used for the mathematical notation. Thus, also in Markdown the mathematical content is embedded as LaTeX code.
• Math markup in HTML:
  For display of the formatted text online in a browser, the original markup (Markdown/LaTeX) needs to be converted (see below) to HTML with some suitable formatting for the mathematical content. Either the LaTeX can be preserved or turned into MathML , a dedicated XML format for describing mathematical content.
• Rendering of math markup:
  The most widely-used way of rendering mathematical content in web pages is MathJax (see also the corresponding Wikipedia page ), an open-source JavaScript library that works in all browsers without any setup by the user (except enabling JavaScript). It can render LaTeX directly but also MathML. Moreover, some browsers (mainly Firefox and Safari but not Chrome) have also native support for displaying MathML, i.e, without the need for an additional display engine such as MathJax. The advantage of employing the browser for MathML rendering is that it is faster and typically blends better into the regular text. The disadvantage is obviously that it is not supported by all browsers and does not support rendering of LaTeX directly.
• Convertesion to HTML:
  The original markup from the exercises templates needs to be converted to HTML and the most powerful document converter for this is Pandoc (see also the corresponding Wikipedia page ). It can convert both Markdown and LaTeX source files to HTML, either with LaTeX embedded for MathJax or with MathML (among various other options). Moreover, LaTeX (but not Markdown) exercises can be converted to HTML using the TeX-to-MathML converter TtM . (R/exams also provides a few further options which are typically of less interest due to lower quality, such as TtH or rendered images.)
• Defaults in R/exams:
  All exams2xyz() functions that produce HTML-based output offer a converter = argument. By default, this is configured to produce HTML with embedded MathML because this can be rendered both by MathJax in all browsers as well as by some browsers directly. The default is is converter = "pandoc" (equivalent to "pandoc-mathml" ) for R/Markdown exercises and converter = "ttm" for R/LaTeX exercises, respectively. Whether MathJax is enabled varies across output formats or might depend on the learning management system.

Why does all of this matter?

As a simple illustration of the strengths and weaknesses of the different approaches, the deriv exercise template (computation of a derivative using the product rule) is converted to HTML using exams2html() . Here, the R/LaTeX version of the exercise is used ( "deriv" or equivelently "deriv.Rnw" ) but using the R/Markdown version ( "deriv.Rmd" ) yields almost the same output.

The following examples and resulting screenshots contrast the output between Firefox and Chrome. By clicking on the screenshots you can also see what the HTML pages look like in your own browser.

MathML rendered by browser

By default, exams2html() generates HTML with MathML embedded and uses a template that does not enable MathJax.

library("exams")
set.seed(1090)
exams2html("deriv")

The screenshots that the native MathML support in Firefox leads to output that renders fast and smoothly. However, the lack of native MathML support in Chrome means that the exercise cannot be displayed correctly.

MathML rendered by MathJax

To easily explore the effect of MathJax rendering exams2html() supports the argument mathjax = TRUE which inserts the MathJax