What's New in PreTeXt?

FYMSiC online conference

Sean Fitzpatrick
University of Lethbridge

May 4th, 2022

What is PreTeXt?

The basics

PreTeXt is an XML vocabulary for authoring scholarly works, along processing tools.

Currently supported formats include:

  1. HTML (fully supported)

  2. PDF, via (fully supported)

  3. EPUB (supported, with some effort)

  4. Jupyter (works, with quirks)

  5. Braille (supported, I think — haven't tried it)

  6. Runestone

  7. Slides (like these ones!)

Processing

Processing of the XML source uses XSLT style sheet transforms.

Traditionally, this involved the use of a program called xsltproc, along with a number of auxilliary programs to handle images and other components.

OK if you use Linux, but intimidating to the new user. Commands could get complicated. Most people relied on Bash scripts or makefiles.

Oh, and getting everything working on Windows was a nightmare.

Why use it?

The motto: “Write once, read anywhere.”

  • Variety of formats makes books more portable and accessible.

  • Speaking of accessibility: the HTML works with screen readers and other accessibility tools.

  • Interactive elements, like video, 3D Asymptote, GeoGebra, Desmos, Sage Cell, and WeBWorK exercises, are all supported.

  • You'll be part of an awesome, supportive community of educators.

So, what's new?

As the user base has grown, so has the need to make things more user-friendly. New tools include:

  • Authoring tools: syntax highlighting and tag completion

  • Processing tools: the “PreTeXt-CLI” (command-line interface), a Python package that automates a lot of the work involved in building your book.

  • Publishing tools: don't have a webserver to host your book? PreTeXt can now automatically publish your book to a GitHub Pages site.

Authoring

The PreTeXt language

PreTeXt uses XML, which will be new to many authors. If you've used HTML and before, the learning curve isn't too steep.

  • XML is used to handle structure: sections, definitions, theorems, examples, etc..

  • Anything that happens in a math environment is standard .

  • Forgotten closing tags become the new forgotten closing brace. (But they're easier to track down!)

Editor tools

Three modern text editors have access to an add-on package that adds support for PreTeXt: Sublime Text, Atom, and VSCode.

PreTeXt support includes syntax highlighting and tag completion. Tag completion means you don't have to remember exactly what all the tags are. Not sure how to format a theorem? Type thm, hit tab, and out comes:

<theorem xml:id="thm-">
  <statement>
    <p>

    </p>
  </statement>
</theorem>

Support

The PreTeXt Guide has instructions for all commonly-encountered scenarios.

When you're stuck, the pretext-support Google group is almost always quick to respond, and helpful.

You can also follow the #PreTeXtGang on Twitter.

Processing

Prerequisites

To get started, your computer will have to have the following:

  1. A Python installation, at version 3.9 or newer. When installing on Windows, be sure to add it to the PATH.

  2. A working distribution, if you want to be able to produce PDF.

  3. If you have images written using TikZ code, you need a helper application called pdf2svg.

  4. Other features might require additional software (like Sage).

  5. You'll need a command prompt. On Windows, PowerShell will do, but most people prefer Git Bash.

Installing PreTeXt

In a terminal, type:

pip install pretextbook
Now wait about 30 seconds.

That's it!

Using the PreTeXt-CLI

There are a few commands you need to build your PreTeXt book. When you're starting out, you should just need the basic commands. As you add more features to your book, you might need to modify things a bit.

  • pretext new book

    Automatically generate a directory with the expected structure.

  • pretext build html

    Build the HTML version of your book. (If you have diagrams that need to be built, pretext build html -d.)

  • pretext build pdf or pretext build latex

    Builds PDF directly, or the file if you need it.

  • pretext view html

    Open your HTML textbook on a local webserver.

Publishing

DIY

When the only version of our book is PDF, publishing isn't a big deal. Put the file on your LMS, and email a copy to your bookstore for print on demand.

But now you want to host HTML. If you (or your department) maintains a webserver, and you can add whatever you want, great! Use that.

If not...

GitHub

Additional prerequisites:

  • A GitHub account

  • Software for using git.

  • An SSH key.

If your PreTeXt source is on GitHub, the PreTeXt-CLI now has a pretext deploy command.

This automatically creates a folder with your HTML, and pushes it to GitHub.

On GitHub, you can select that folder in your “GitHub Pages” settings, and voilà! Your book is published.

PreTeXt-adjacent cool things

Runestone Academy

Runestone Academy is a site for open source, interactive textbooks, primarily for computer science.

The Runestone Interactive software can be run on a local server, or books can be hosted on the Runestone Academy website.

PreTeXt in Runestone

There is a “publisher option” that results in HTML output compatible with Runestone Academy.

You can choose to have your book hosted there, or on a Runestone server you run yourself.

Once your book is on Runestone, students can log into it. This allows them to highlight and annotate.

More importantly, it lets them complete problems in the book and have their progress saved. Scores can be downloaded by the instructor.

Runestone in PreTeXt

A recent development has freed some of the Runestone interactive elements from the Runestone infrastructure, allowing them to be used in a PreTeXt book.

This includes interactive exercises such as Parson's problems, and live coding.

This is still a work in progress. For a sample of current experiments, see the Sample Runestone Book on the PreTeXt website.

CheckIt

Steven Clontz has written a web application called CheckIt.

CheckIt uses PreTeXt as an element for algorithmically generating homework problems. The app is written with standards-based grading in mind: instructors can quickly and easily generate many versions of an assessment, with each problem tied to a particular “standard” or learning outcome.