Merge pull request matplotlib#20706 from kir0ul/issue_17774

Include `underscore.sty`

Author: QuLogic

doc/api/next_api_changes/development/20706-AP.rst

@@ -0,0 +1,4 @@
+Improve underscore support in LaTeX
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `underscore <https://ctan.org/pkg/underscore>`_ package is now a requirement to improve support for underscores in LaTeX.

doc/devel/dependencies.rst

@@ -222,9 +222,13 @@ Required:
 
 * a minimal working LaTeX distribution
 * `Graphviz <http://www.graphviz.org/download>`_
-* the LaTeX packages *cm-super* and *dvipng* (if your OS bundles TeXLive, the
+* the following LaTeX packages (if your OS bundles TeXLive, the
   "complete" version of the installer, e.g. "texlive-full" or "texlive-all",
-  will often automatically include these packages)
+  will often automatically include these packages):
+
+  * `cm-super <https://ctan.org/pkg/cm-super>`_
+  * `dvipng <https://ctan.org/pkg/dvipng>`_
+  * `underscore <https://ctan.org/pkg/underscore>`_
 
 Optional, but recommended:
 

lib/matplotlib/tests/test_usetex.py

@@ -100,8 +100,22 @@ def test_usetex_packages(pkg):
                                   text.get_window_extent())
 
 
-def test_textcomp_full():
-    plt.rcParams["text.latex.preamble"] = r"\usepackage[full]{textcomp}"
+@pytest.mark.parametrize(
+    "preamble",
+    [r"\usepackage[full]{textcomp}", r"\usepackage{underscore}"],
+)
+def test_latex_pkg_already_loaded(preamble):
+    plt.rcParams["text.latex.preamble"] = preamble
     fig = plt.figure()
     fig.text(.5, .5, "hello, world", usetex=True)
     fig.canvas.draw()
+
+
+def test_usetex_with_underscore():
+    plt.rcParams["text.usetex"] = True
+    df = {"a_b": range(5)[::-1], "c": range(5)}
+    fig, ax = plt.subplots()
+    ax.plot("c", "a_b", data=df)
+    ax.legend()
+    ax.text(0, 0, "foo_bar", usetex=True)
+    plt.draw()

lib/matplotlib/texmanager.py

@@ -174,6 +174,12 @@ def _get_preamble(self):
             # relies on a custom preamble to change the geometry.
             r"\usepackage[papersize=72in, margin=1in]{geometry}",
             self.get_custom_preamble(),
+            # Use `underscore` package to take care of underscores in text
+            # The [strings] option allows to use underscores in file names
+            r"\makeatletter"
+            r"\@ifpackageloaded{underscore}{}"
+            r"{\usepackage[strings]{underscore}}"
+            r"\makeatother",
             # textcomp is loaded last (if not already loaded by the custom
             # preamble) in order not to clash with custom packages (e.g.
             # newtxtext) which load it with different options.