Math Magic

Math helps us to make sense of the world and make it a better place. The language of math (formulas and equations) is universal, but it is also universally difficult to render handwritten formulas into digital form for the computer.

Thirty years ago, math graduate students would pay programmers to render their beautifully drawn mathematical formulas for the computer because the process took twice as long as the original drawing, regardless of the available software. Even today, entering a complex mathematical formula can be much slower than writing the same formula by hand. MathLex [1], a little-known JavaScript utility, helps solve this problem. It parses math input notation into a syntax tree and then renders the notation as several target outputs, which you can then use on your web pages (Figure 1).

Figure 1: In addition to the formula, the MathLex demo also shows how it parses the formula internally, as well as the formula's LaTeX and Sage versions.

MathLex was developed by Matthew J. Barry along with Philip B. Yasskin and others as part of Barry's undergraduate thesis about 10 years ago. While the project basically stalled after initial development, you can still find it (along with a demo) on GitHub [1] (Figure 2).

Figure 2: The MathLex demo is an HTML page that will work in any browser.

Barry developed MathLex because he found math entry systems like MathML and even LaTeX too slow to use, too complex, and sometimes not very good at preserving semantics (the actual meaning of each element of a formula). He designed MathLex to let users enter complex formulas using a syntax as close as possible to handwritten math, but unambiguous in its mathematical meaning, without giving up compatibility with popular standards like MathML or MathJax (Figure 3). In addition, Barry made MathLex compatible with any browser or operating system, without the portability issues of technologies like Flash.

Figure 3: MathLex also supports the MathML markup language and the MathJax library.

In this article, I will show you how to install MathLex on Linux, how to use it to write formulas, and also how to embed it into any web page.

Installing MathLex

Unfortunately, MathLex is not packaged in distribution-native formats like .deb or .rpm. The easiest way to install it on your Linux box is to build it locally using the Yarn JavaScript package manager [2].

To get a working copy of MathLex on your computer, start downloading all the source code, with git or as a single ZIP archive. Once the code is in a folder on your computer, go to the folder from the command line and type the following two commands at the prompt:

yarn
yarn build

With any luck, installation should complete in a minute or two. On Ubuntu, however, I came across the Yarn error known as "There are no scenarios; must have at least one." It turns out that Ubuntu (and possibly other Linux distributions) does not install the default version of Yarn recommended by its developers. Instead it installs a different version found inside another package called cmdtest|. You can remove this package and then install the original one for Yarn, as explained on Stack Overflow [3].

Using MathLex

The most difficult part of writing formulas with MathLex is knowing all the math you will need to use and all of MathLex's functions. In regards to learning the MathLex syntax, Yarn will place a file called index.html in the build/demo folder (index.html is the HTML page shown in Figures 1 and 2).

In addition to the Syntax and Topic links at the top of Figure 2, the bottom part of the HTML page contains many sample formulas that you can load in the entry box and modify as you wish (Figure 4), convert to other formats like SVG (Figure 5), or even use to learn how the native format of MathLex works (Figure 6). Thanks to those tips and examples, and to the fact that the rendering and parse boxes in Figure 2 change as you type, attempting to write formulas in the demo is by far the quickest and most effective way to learn the MathLex syntax.

Figure 4: You can render the formulas in several formats, depending on your needs.

Figure 5: The SVG version of the same formula shown in the previous figures.

Figure 6: For study or documentation purposes, you can also view the plain source that MathLex uses to represent formulas.

One thing I found confusing in the demo was that some markers (delimiters in MathLex terminology) can be written with or without colons. In handwritten math, for example, the absolute (i.e., without a positive or negative sign) of some variable is written by placing that variable between two vertical bars. Unsurprisingly, MathLex lets you specify the absolute value of a variable by wrapping it inside pipe characters (e.g., |X|). For MathLex, however, even |:X:| is a perfectly valid syntax. The only thing you cannot do is mix the forms (i.e., you cannot write |:X|). Just remember this, and everything will be fine.

Using MathLex on the Web

Listing 1, the source code for the custom MathLex page shown in Figures 7, 8, and 9, outlines what you need to easily use MathLex on any web page. To get the working MathLex interface shown in Figure 7, I copied the relevant part of the demo's index.html file into an empty file, saved it with an .html extension, and rewrote the header and some other strings.

01 <!doctype html><html lang="en">
02 <head>
03 <meta charset="utf-8">
04 <title>MathLex Demo</title>
05 <link rel="stylesheet" href="css/normalize.min.css">
06 <link rel="stylesheet" href="//fonts.googleapis.com...">
07 <link rel="stylesheet" href="css/style.min.css">
08 <script src="https://cdnjs.cloudflare.com..."></script>
09 <link href="main.css" rel="stylesheet">
10 </head>
11 <body>
12 <h1>Let's try MathLex for Linux Magazine!</h1>
13
14 <div role="main">
15
16 <div class="inbox"><a class="delete-icon" href="#" title="clear">clear</a>
17 <textarea class="expand" id="math_input" name="math" placeholder="Linux Magazine test: just enter any formula here..."></textarea>
18 </div>
19
20 <div id="math_output">\[\mathrm{\LaTeX\ Output\ for\ LM\ readers}\]</div>
21
22 <div class="outbox"><label for="tex_output">Translated LaTeX Code</label>
23
24 <div id="tex_output"><code>Output LaTeX Code</code></div></div>
25
26 <div class="outbox"><label for="sage_output">Translated Sage Code Incomplete</label>
27
28 <div id="sage_output"><code>Output Sage Code</code></div></div>
29
30 <div class="outbox"><label for="ast_output">Interpreted Syntax Tree</label>
31
32 <div id="ast_output"><code>Output Syntax Tree</code></div></div>
33
34 <script src="../mathlex.js"></script>
35 <script src="http://code.jquery.com/jquery..."></script>
36 <script src="index.js"></script>
37 </body>
38 </html>

Figure 7: To create your own MathLex-capable web pages, just grab the right code from the MathLex demo and customize it.

Please note in Listing 1 that I shortened the lengthy URLs for the font and JavaScript libraries loaded in lines 6, 8, and 35 for readability. The actual URLS may differ depending on the MathLex version you use.

Regarding the libraries, there are two things to pay attention to in Listing 1. First, you must include the whole header of the demo index.html file (lines 1 to 11), but do not shorten the URLS as I did for readability.

Second, take all the files that contain the MathLex stylesheets, as well as its actual source code from the demo folder, and copy these alongside your HTML page. I used the April 2021 version of MathLex for this article, so in Listing 1 those files are the stylesheets called in lines 7 and 9 and the JavaScript files, mathlex.js and index.js (lines 34 and 36). If you use a newer version, please check the header and the bottom of the index.html file for other files you should include.

The rest of Listing 1 is easy to understand by just comparing it with Figures 7 through 9. Line 12 produces the "Let's try MathLex for Linux Magazine!" header, and lines 16 to 18 produces the text entry area, initially filled with the placeholder text shown in line 17, where you can write your formulas (Figure 8). The same formulas are rendered in the div element of line 20, whose initial value is also customizable by changing the text inside the curly brackets.

Figure 8: The custom page generated by Listing 1 works just like the original demo. Notice how the interactive renderer displays formulas in red until they are complete and error-free.

Finally, the three pairs of div elements starting on lines 22, 26, and 30 are the HTML markup that renders (together with their headers) the three boxes where MathLex displays LaTeX code, Sage Code and, respectively, its own internal syntax tree (Figure 9).

Figure 9: The same formula shown in Figure 8 is now in black because it is complete, and all parts follow the intuitive MathLex syntax.

The final part of the page (lines 34 to 36) loads the MathLex source code as well as the jQuery JavaScript library [4], which makes the whole page interactive.