From 44a6337669c29361cbb7dd6b743bea1fc3cb2539 Mon Sep 17 00:00:00 2001
From: Vishal Pankaj Chandratreya <19171016+tfpf@users.noreply.github.com>
Date: Sat, 11 Apr 2026 23:49:37 +0530
Subject: [PATCH] Implement underline logic as in TeX

---
 .../next_whats_new/underline-23616.rst        |  12 ++++++++++++
 lib/matplotlib/_mathtext.py                   |  18 ++++++++++++++++++
 .../test_mathtext/mathtext1_dejavusans_09.png | Bin 0 -> 2548 bytes
 lib/matplotlib/tests/test_mathtext.py         |   1 +
 4 files changed, 31 insertions(+)
 create mode 100644 doc/release/next_whats_new/underline-23616.rst
 create mode 100644 lib/matplotlib/tests/baseline_images/test_mathtext/mathtext1_dejavusans_09.png

diff --git a/doc/release/next_whats_new/underline-23616.rst b/doc/release/next_whats_new/underline-23616.rst
new file mode 100644
index 000000000000..184c588b842c
--- /dev/null
+++ b/doc/release/next_whats_new/underline-23616.rst
@@ -0,0 +1,12 @@
+Underlining text while using Mathtext
+-------------------------------------
+
+Mathtext now supports the ``\underline`` command.
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+
+    plt.text(0.4, 0.7, r'This is $\underline{underlined}$ text.')
+    plt.text(0.4, 0.3, r'So is $\underline{\mathrm{this}}$.')
+    plt.show()
diff --git a/lib/matplotlib/_mathtext.py b/lib/matplotlib/_mathtext.py
index 21ec24d73286..b04386e7666a 100644
--- a/lib/matplotlib/_mathtext.py
+++ b/lib/matplotlib/_mathtext.py
@@ -2207,6 +2207,8 @@ def csnames(group: str, names: Iterable[str]) -> Regex:
 
         p.overline = cmd(r"\overline", p.required_group("body"))
 
+        p.underline = cmd(r"\underline", p.required_group("body"))
+
         p.overset  = cmd(
             r"\overset",
             p.optional_group("annotation") + p.optional_group("body"))
@@ -2259,6 +2261,7 @@ def csnames(group: str, names: Iterable[str]) -> Regex:
             | p.underset
             | p.sqrt
             | p.overline
+            | p.underline
             | p.text
             | p.boldsymbol
             | p.substack
@@ -2945,6 +2948,21 @@ def overline(self, toks: ParseResults) -> T.Any:
         hlist = Hlist([rightside])
         return [hlist]
 
+    def underline(self, toks: ParseResults) -> T.Any:
+        body = toks["body"]
+        state = self.get_state()
+        thickness = state.get_current_underline_thickness()
+        # Place the underline below `body` (node735).
+        vlist = Vlist([
+            Hlist([body]),
+            Kern(3 * thickness),
+            Hrule(state, thickness),
+        ])
+        delta = vlist.height + vlist.depth + thickness
+        vlist.height = body.height
+        vlist.depth = delta - vlist.height
+        return [Hlist([vlist])]
+
     def _auto_sized_delimiter(self, front: str,
                               middle: list[Box | Char | str],
                               back: str) -> T.Any:
diff --git a/lib/matplotlib/tests/baseline_images/test_mathtext/mathtext1_dejavusans_09.png b/lib/matplotlib/tests/baseline_images/test_mathtext/mathtext1_dejavusans_09.png
new file mode 100644
index 0000000000000000000000000000000000000000..9d96e8eb87b9c411c40faad7d8cc67ea20306a10
GIT binary patch
literal 2548
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
KMNUMnLSTZgAf;pg

literal 0
HcmV?d00001

diff --git a/lib/matplotlib/tests/test_mathtext.py b/lib/matplotlib/tests/test_mathtext.py
index 33fb8918d22a..a8f9236b5208 100644
--- a/lib/matplotlib/tests/test_mathtext.py
+++ b/lib/matplotlib/tests/test_mathtext.py
@@ -154,6 +154,7 @@
     r'$\left\lbrace\frac{\left\lbrack A^b_c\right\rbrace}{\left\leftbrace D^e_f \right\rbrack}\right\rightbrace\ \left\leftparen\max_{x} \left\lgroup \frac{A}{B}\right\rgroup \right\rightparen$',
     r'$\left( a\middle. b \right)$ $\left( \frac{a}{b} \middle\vert x_i \in P^S \right)$ $\left[ 1 - \middle| a\middle| + \left( x  - \left\lfloor \dfrac{a}{b}\right\rfloor \right)  \right]$',
     r'$\sum_{\substack{k = 1\\ k \neq \lfloor n/2\rfloor}}^{n}P(i,j) \sum_{\substack{i \neq 0\\ -1 \leq i \leq 3\\ 1 \leq j \leq 5}} F^i(x,y) \sum_{\substack{\left \lfloor \frac{n}{2} \right\rfloor}} F(n)$',
+    ' '.join(f'${c}\\underline{{{c}}}$' for c in 'abfghy') + r' $\underline{\left(\dfrac{num}{\underline{den}}\right)}^{\underline{p_1}}$',
 ]
 
 digits = "0123456789"