Looks good! I think it makes sense to add a brief What's new for this to make users aware that it is added.

Also, I think it may be enough to have a "lightweight" test for this as it doesn't seem very dependent on the font:

@anntzer I think you as our TeX expert should review this.

Sure, l'll need a couple of days though.

This seems reasonable, but 1) do you know why the overline() implementation is so different, using a fill instead? (which seems inconsistent with the TeXbook); 2) the TeXbook (rules G9/G10 p443) add an extra thickness of whitespace clearance over the overline / under the underline; do you know why they are not needed here (if they indeed aren't)?

the TeXbook (rules G9/G10 p443) add an extra thickness of whitespace clearance over the overline / under the underline

I think that extra space is used to set the minimum leading.

If the leading is high, the vertical distance between the tops of the Ts and the underscores on the previous lines remains unchanged even if the underscores are underlined. (As if the underline wasn't there at all.)

Upon reducing the leading, the Ts remain some distance away from the underline. It's like the underline forces the next line to go lower if it is too close.

I have not looked through Mathtext's leading rules, but it certainly looks like it's better to follow what TeX does. I will update this. Getting second thoughts about this now. Should I add that space at the bottom, or leave this as it is?

do you know why the overline() implementation is so different, using a fill instead

That's a good question, one which I wondered myself, but couldn't figure out. In fact, I haven't completely understood how glue works in Mathtext.

Could the differences have to do with the rule being incorrectly rendered inverted? #31046 (comment)

As pointed out by QuLogic and anntzer, the rendering issue is now resolved. Time to bring this back.😴

Preliminary Check

import string

import matplotlib.pyplot as plt

plt.rcdefaults()

fig, ax = plt.subplots(figsize=(20, 5))
ax.text(
    .5, .5, " ".join(f"${c}\\underline{{{c}}}$" for c in string.ascii_lowercase),
    size=30, ha="center", va="baseline",
)
ax.axhline(.5)
fig.savefig("underline.png")
fig.savefig("underline.svg")
plt.show()

The underlines are drawn as described in TEX: The Program. Thus, text with descenders will push the underline lower. This is the expected behaviour; see exercise 18.26 on page 178 of The TeXbook.

Caveats

• The lines under 'e' and 'f' are not aligned because their lowermost points aren't aligned. (This will be font-specific.)

do you know why the overline() implementation is so different, using a fill instead? (which seems inconsistent with the TeXbook)

I can make a guess.

The line above the body of a radical must touch the top of the radical (a tick mark), so it is imperative that the line be rendered at the correct height. This combined with the fact that the text under radicals (and overlines) is supposed to be rendered in cramped style might explain why the space between it and the body was not calculated but filled up with stretchable glue. You can see this in the sqrt function. That logic appears to have been reused for overline.

the TeXbook (rules G9/G10 p443) add an extra thickness of whitespace clearance over the overline / under the underline; do you know why they are not needed here (if they indeed aren't)?

I am now fairly sure that this was done to give the line some space between it and the previous or next lines. I suppose the same could be done here, but it is not clear why he set the depth directly instead of adding a vertical space.

Comparing with usetex=True, this does look pretty consistent with LaTeX, though it seems our rule thickness is a bit bigger (and so the gap is bigger).

But the inconsistency with the underline thickness does make me wonder if we should disable snapping on all mathtext boxes. Any thoughts @anntzer @tacaswell? Unfortunately, this would cause about 120 test image changes.