Skip to content

Fix malformed $\LaTeX$#1937

Open
NathanielBlairStahn wants to merge 17 commits intomainfrom
ndbs/fix-math
Open

Fix malformed $\LaTeX$#1937
NathanielBlairStahn wants to merge 17 commits intomainfrom
ndbs/fix-math

Conversation

@NathanielBlairStahn
Copy link
Copy Markdown
Contributor

Fix a bunch of errors in our displayed equations, with the help of GitHub Copilot. The two most common errors were

  • Unescaped underscores within a \text command, e.g., \text{deaths_c500} instead of \text{deaths\_c500}, leading to a "'_' allowed only in math mode" error. The first version is not valid $LaTeX$ because it tries to interpret _ as a subscript, which is illegal in text mode, so the underscore needs to be escaped if we want a literal underscore.
  • Usage of \begin{aligned*}...\end{aligned*} within Sphinx's .. math:: directive without the :no-wrap: option, which leads to an "Erroneous nesting of equation structures" error. There are two ways to fix this: Either add the :no-wrap: option to the math directive to prevent Sphinx from erroneously wrapping it in another environment, or replace the align* environment with the aligned environment, which is designed to be used inside another equation environment.

These errors have always been present in our code, but I'm guessing they only showed up recently due to an update to MathJax, which renders the equations in web browsers. I'm not totally sure, but most likely older versions of MathJax were more forgiving of $LaTeX$ commands that didn't follow proper syntax.

The AI caught a few other instances of typos, bad formatting, and bad syntax that I also fixed, even though they weren't throwing errors.

I can't guarantee that I've caught all the errors, or that I've necessarily implemented the correct fix in all instances since the fixes were made programmatically via Python scripts from the AI. After I thought I had caught everything, I tried having the AI run a headless browser (Playwright) to scrape error messages from the rendered web pages (this idea was one of the AI's suggestions), and it caught one more that had been missed. So maybe that means now there shouldn't be any more errors?

@NathanielBlairStahn NathanielBlairStahn added the documentation clean up Trivial changes such as link fixes, typo fixes, added notes, etc. label May 2, 2026
@NathanielBlairStahn
Copy link
Copy Markdown
Contributor Author

I had the AI search for missed errors again, this time by running MathJax directly, and it found a few more that escaped both the pattern matching in the initial Python script and the Playwright page scraping for some reason.

@NathanielBlairStahn NathanielBlairStahn changed the title Fix malformed $LaTeX$ Fix malformed $\LaTeX$ May 4, 2026
@NathanielBlairStahn
Copy link
Copy Markdown
Contributor Author

@zmbc
Copy link
Copy Markdown
Collaborator

zmbc commented May 5, 2026

Copy link
Copy Markdown
Collaborator

@zmbc zmbc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I randomly sampled parts of this PR and they all looked reasonable

Copy link
Copy Markdown
Collaborator

@SylLutze SylLutze left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to Zeb, I did a bit of random spot checking, I did not do a complete review of all lines.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation clean up Trivial changes such as link fixes, typo fixes, added notes, etc.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants