Fix nested braces in mathtext \text arguments - #32147

Thank you for opening your first PR into Matplotlib!

If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks. We also ask that you please finish addressing any review comments on this PR and wait for it to be merged (or closed) before opening a new one, as it can be a valuable learning experience to go through the review process.

You can also join us on discourse chat for real-time discussion.

For details on testing, writing docs, and our review process, please see the developer guide.
Please let us know if (and how) you use AI, it will help us give you better feedback on your PR.

We strive to be a welcoming and open project. Please follow our Code of Conduct.

pyparsing has the builtin nested_expr; could that not be used instead of building our own machinery?

@anntzer Good suggestion. I looked at this. nested_expr works well for \substack, where the body is recursively parsed tokens and a nested list is the natural result.

For \text, the argument is a brace-balanced literal string: nested braces are TeX groups (not rendered), {/} are literal braces, and interior whitespace must be preserved.

nested_expr returns nested lists and, by default, skips whitespace between chunks, so we’d still need custom content, escape handling, and a flatten/unescape parse action. That ends up about as much machinery as _BracedText, with more risk around spaces next to escapes.

Happy to switch if you’d still prefer the nested_expr shape for consistency. Please lmk!

Friendly bump. Circling back on the nested_expr question from Aug 2. Happy to refactor if you’d still prefer that for consistency; otherwise I think the current _BracedText approach is ready for another look. Thanks!

I am a bit confused why only \text needs this handling. In theory mathtext strings can be full of balanced braces a bit everywhere, which are no-ops (unless preceded by a command), so why is handling of balanced braces specifically different here?

Good question. They aren't, except for \text.

In math mode, nested braces already go through p.group / optional_group / required_group, so they're no-ops as you describe. That's also why \mathrm{{example}} works, \mathrm is a font-prefixed group, not a delimited string.

\text never used that path. Its argument is a text-mode literal (keep spaces, don't treat _/^ as sub/super, \{/\} for actual braces), which is why it was a QuotedString to begin with. That matcher just happens to end at the first }.

Reusing optional_group would get nested braces for free, but it would also parse the body as math, which isn't what \text does. _BracedText is only replacing that quoted-string matcher, not adding a second grouping system.

A recursive text-mode group would be more consistent long-term, but it seemed out of scope for this bug.

Thanks for the review. Agreed it's a bit of custom parsing; I went this way to keep \text as a quoted literal. Happy to revisit if we want it on the recursive-group path later. We can also open a follow-up issue to investigate through it.

Looking at the reduced coverage, I guess you should also add some invalid test cases.

@meeseeksdev backport to v3.11.x