Putting a math- & code-heavy textbook online

Some changes arrive with great drama and attention. Others creep in stealthily, like the gradually warming water that boils the proverbial frog (contrary to reality).

I can’t think of the last time I welcomed the sight of a printed journal in my mailbox. Though I might print the occasional article that needs to be pored over slowly, I’ll recycle that copy after a bit; the electronic version is the one that I archive. I got rid of my last filing cabinet years ago. The old papers and notes that I pulled out and saved from it have lain undisturbed on my bookshelf ever since.

Most of my pleasure reading is also done on devices rather than paper now. The portability and lack of clutter usually end up being decisive advantages for me. It’s a preference, not an inevitable necessity, unlike, say, the Oxford comma.

I haven’t found solid data on the matter, but my sense is that over the past five years or so, college student preferences for textbooks have been shifting toward the electronic. It’s worth considering that the iPhone is still only about 12 years old. Students who have had ubiquitous screens since toddlerhood have yet to make it to college. In other words, it’s still early days.

We’re also in early days when it comes to exploiting the potential of electronic presentation. Many of the advantages of screens are forfeited when the electronic format is a skeuomorphic mess. As pointed out by James Somers in The Atlantic in 2018, PDF is essentially a simulation of paper and should be considered obsolete as a method of presenting technical material electronically.

Somers profiles two alternatives: Mathematica and Jupyter notebooks. Both offer semantic markup as well as computational interactivity. However, Mathematica is a closed, proprietary system, which limits its appeal as a publishing platform. And one does not need to spend a lot of time with Jupyter notebooks to see that they are oriented toward short, standalone documents.

There is a middle ground: good old-fashioned HTML, with a dash of MathJax for equations. It’s not (inherently) interactive, but it’s light on resources and can display on just about any device. Hence, once I became determined to put my textbook with Rich Braun, Fundamentals of Numerical Computation, the question for me became: how do you author a book that includes lots of math and code in HTML form?

Now, the original textbook was produced using numerous LaTeX files and MATLAB scripts and functions. In my defense, I had cobbled all that together back when publish in MATLAB still seemed pretty cool. My scripts actually run and include all the actual code each time the PDF is made. Surely, I thought, the right solution would be to publish directly in HTML rather than PDF. Right?

Not right. I’m not even going to bother to link to all the LaTeX-to-HTML converters I tried, seeing as how I’ve already given enough of my lifetime over to them. It’s not that those tools aren’t made by clever people, and to some degree they do work. It just seems to be a fiendishly hard problem. Part of the issue is that some of TeX/LaTeX’s great strengths, programmability and extensibility, require a monumental effort to duplicate. This is a guess, but I speculate too that the whole foundation of TeX—absolute and precise control over appearance—is the antithesis of the HTML model of “let the browser render.”

Once I was resigned to the idea that my precious LaTeX files were going to have to be ported into some other form, I began to think about what the destination format should be. I briefly thought about using Jekyll, which I’ve used for course notes in the past. It’s fairly simple, but not quite powerful enough for a book project.

Next up was PreTeXt, which I used this past spring to write course notes for an LA/DE course. This project is maintained by people who care a lot about putting math on the web, and there’s a great free linear algebra textbook based on it. PreTeXt requires authoring directly in XML, though, which is not for the faint of heart. Worse, it has no mechanism for including code other than Sage. Sage is great but not used for this project. I hacked and kludged my way to getting some short MATLAB codes in my PreTeXt notes, but it was not feasible for the level of code integration we need for the textbook.

Practically by accident, I found a superior solution for my purposes: Jupyter Book. It allows writing content in Markdown or Jupyter notebooks, or a mixture of both. It supports MathJax equations, cross-references, footnotes, indexing, and bibliographies. Jupyter Book is built on top of Sphinx, which allowed me to fold in an extension for theorems. And it generates static HTML content, but you can direct it to include a link on every notebook page to an interactive Binder instance.

You can see for yourself the result for (at this writing) the first 6 chapters of FNC.

This is very much a direct import of a book to an online format. I have not yet even enabled interactivity due to painfully slow Julia package loading times. Down the line it makes sense to take greater advantage of the format to include, for instance, video lectures and demos of the material, and I’m sure further adaptations will be called for. One great thing about an online book is that it is never “finished;” it can be continuously improved. That’s one of the bad things too, in terms of my work-life balance.

Professor of Mathematical Sciences

My research interests are in scientific computation, mathematical software, and applications of mathematics in the life sciences.

Related