Notices of the American Mathematical Society
Welcome to the Notices of the American Mathematical Society.
With support from AMS membership, we are pleased to share the journal with the global mathematical community.
PDFLINK |
Write Better with PreTeXt
I still remember the excitement of learning LaTeX while attending a Research Experience for Undergraduates (REU) the summer before my last year of undergrad. Part of the appeal was the ease with which one could write mathematical expressions, but more so I loved that I could just start writing and not worry about getting the formatting correct. During grad school, I vowed to write all my homework, as well as course notes for the classes I was taking and teaching, in this magical text format that promised to keep what I wrote always available and easily modifiable in the future. In my early years as an assistant professor, I was often rescued, when time was short, by being able to modify notes or a classroom activity from a previous semester. And when a colleague would ask for my materials to help them plan their class, I could easily share the vault of content I had created in a way they could easily use or adapt.
While LaTeX is still an amazingly useful tool, it suffers from two main issues that hinder the sharing of materials created with it. First, LaTeX lets us use a large number of packages and custom macros to tweak everything. In fact, the enticement of writing without concern for formatting quickly evaporates when you start tinkering; LaTeX let’s you make your document look any way you might want. At first, this seems like a strength, but it means that sharing code can require lots of additional modifications to make two documents compatible.
Second, and far more serious, is that for the most part, LaTeX compiles to PDF. Suppose you write daily lecture notes for your class: do you compile a different PDF for each day, requiring students to download lots of different files to find what they want, or one large PDF that must be updated regularly (and so redownloaded regularly)? What if you find some typos and fix it: do you know students have the most recent version? When the students get your beautifully laid out document, how useful will it be when they need to pinch and zoom to view it on their phones? And what about your visually impaired student who uses a screen reader? PDFs are notoriously bad for accessibility, to the point that some universities ban their use completely.
Wouldn’t it be nicer to have your course materials on a website that looks great on any sized screen, interacts well with screen readers, is always up-to-date with your latest changes, and even provides interactivity? Solutions to exercises could be hidden until the student clicks to reveal them. Students could run snippets of SAGE or Python code, interact with dynamic graphics, and receive instant feedback on exercises. Imagine if you could create such a site with roughly the same level of difficulty of writing in LaTeX. As a bonus, you could still have a great PDF, compiled from the same set of source files you write for the web. In fact, that same source can be converted to other formats, including Braille. Further, the source will be well structured so you are guaranteed that what you write will be compatible with the content written by anyone else using the format.
If this sounds good, then I would like to invite you to try PreTeXt. Started in 2013 by Rob Beezer, recently retired from the University of Puget Sound, PreTeXt is a markup language designed from the ground up to author scholarly documents, especially in mathematics. Content written in PreTeXt can be converted to multiple output formats, including interactive websites, LaTeX, ePub, and even Braille. The produced LaTeX is structured consistently and would be suitable for submission to research journals; at least one research article is available on arXiv, which accepted the LaTeX produced by PreTeXt without further changes. It has been used extensively to write free, open source textbooks, many of which are featured in the American Institute of Mathematics’ Open Textbook Initiative.
You need not intend to write a free textbook for PreTeXt to be useful. I use it to write all my course notes for each class I teach: as I prepare for each lesson, any notes I write, or exercises I assign, or in-class activities I create, are written in PreTeXt. A few clicks later, I have a PDF version to print out to take with me to class, and an interactive website containing all the material available for students to access from anywhere.
Much like LaTeX, a PreTeXt document is a plain text file (or files), so it can be edited with any text editor (and so you can use all the powerful features of modern text editors). The syntax is XML (it looks similar to the HTML you would see if you look at the source of a website). Thus, you would write a theorem as something like this:
<theorem xml:id="fermat">
<title>Fermat's Last Theorem</title>
<statement>
<p>
The Diophantine equation <m>x^n
+ y^n = z^n</m> has no non-trivial
solutions for any <m>n\ge 3</m>.
</p>
</statement>
<proof>
<p>
Left as an exercise to the reader.
</p>
</proof>
</theorem>
A few aspects of this example are worth pointing out.
- 1.
Mathematical expressions, enclosed in <m> tags, are LaTeX: anything you put between dollar signs can go between <m> tags, and the math will be correctly rendered using MathJax online, LaTeX for pdf, or Nemeth Braille.
- 2.
Yes, there is a lot of “markup” to describe the semantic structure of the text. Please don’t be scared away by this; using autocomplete you don’t have to type out all the opening and closing “tags” (e.g., statement, p, etc.) yourself, and syntax highlighting makes it easy to distinguish between content and markup when you are editing.
- 3.
The markup is exactly what makes PreTeXt so powerful and what will make you a better writer
Alright, perhaps this last point requires further justification. The semantic markup of PreTeXt delegates decisions about visual representation of your content to the software, relieving you of this burden. Consider: what should the source code above look like when it is converted to a PDF or a webpage? Probably some bold text with the word “Theorem” followed by a number…with a period after the number? Then the title should be…bold text also? I think that the text of the statement of theorem should be italic, but maybe that’s for definitions. The text of the proof definitely should not be italic, but maybe it should be indented (or on the webpage even hidden until you click on the word “proof”) and have a nice black square at the end. Perhaps a less trivial theorem requires a proof with multiple paragraphs; should paragraphs start with a tab or be separated by a blank line?
Clearly, our time can be better spent if we just write the content of our document and don’t need to worry about the formatting. This is also the advantage of LaTeX, of course, although there you might worry about whether you (or your collaborators) are using \begin{theorem} or \begin{thm}, for example. Beyond the reminder that we should be writing and not typesetting, thinking about the semantics of our document also helps us write better prose. What is the purpose of this sentence? Am I writing a definition or an axiom? More than once I have been forced to rethink how I was organizing my writing because there was no good way to capture it in PreTeXt, only to realize that the true problem was that my writing was no good in the first place.
There are technical advantages to this approach as well. Suppose you are writing a definition. The word you are giving the definition for should be identified as such. In PreTeXt, you do this by wrapping the word in <term> tags, and usually this is rendered as bold or bold and italic text. Perhaps the publisher wants defined terms underlined, because their font doesn’t show bold nicely. If you used something like LaTeX’s \textbf, a conversion to another output format or style would have to guess which components are terms and which are just bold text. Note also, there is no such thing as bold in Braille.
The advantages of structured, semantic markup for accessibility alone should make PreTeXt a clear choice for adoption as our authoring language. But if you want more, just think of all the cool new ways you can interact with your students when you write with interactivity in mind. Use Asymptote to create a 3D graph of a function that you can drag around to get a better view. Illustrate pointwise and uniform convergence for sequences of functions by including a Desmos or Geogebra applet directly in your notes. Give your students a sequence of statements they need to put in the right order to complete a proof (and check that they got it right). Provide a snippet of code that computes the sum of the first Fibonacci numbers, and let them modify the code to look for a pattern. And since every student has a computer in their pocket, you can engage your students in mathematics any time and any place.
Intrigued? If you would like to give PreTeXt a try, here are a few tips to get started quickly.
- 1.
The easiest way to try out PreTeXt without installing any software is to use a GitHub Codespace (an experience not unlike Overleaf for LaTeX). You can follow the Getting Started Tutorial in the PreTeXt documentation to try this out.
- 2.
If you want to run PreTeXt on your own computer, you will need a recent copy of python installed (3.8 or later). You should also install a modern text editor: I recommend VS Code, which has a plugin called pretext-tools that supports syntax highlighting, as well as buttons to convert your source files into various output formats. Inside VS Code, you can create a new PreTeXt project which will generate the basic structure of the document (just like you get in the cloud-based version above).
- 3.
Start writing! The template for a new project provides a lot of structure for you already. It takes some time to get used to writing the markup, but I promise it gets easier the more you do it. If you are not sure what markup to use, consult either the PreTeXt Guide or click on “view source” in part of the annotated sample article.
- 4.
Ask for help when you are stuck. PreTeXt has a friendly community of authors and developers. We have drop-in zoom “office hours” multiple days a week (see the upcoming schedule) and a Google group for support questions.
I hope it is clear that PreTeXt offers a number of advantages over LaTeX, including the ability to create interactive websites, way better accessibility, and a more semantic markup that encourages good writing habits. The markup allows your source to be converted to multiple output formats, even those suitable for journal publication (this very article was authored in PreTeXt). Recent and ongoing development of tools for writing in PreTeXt make it vastly easier to work with. If you are looking for a way to write and share your mathematical documents in a more effective way, I encourage you to give PreTeXt a try.
Oscar Levin is a professor in the Department of Mathematical Sciences at the University of Northern Colorado. His email address is oscar.levin@unco.edu.
Article DOI: 10.1090/noti3056
Credits
Photo of Oscar Levin is courtesy of the University of Northern Colorado.