oscargus
diff --git a/‎tutorials/text/mathtext.py‎
Lines changed: 3 additions & 3 deletions b/‎tutorials/text/mathtext.py‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎tutorials/text/pgf.py‎
Lines changed: 3 additions & 3 deletions b/‎tutorials/text/pgf.py‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎tutorials/text/usetex.py‎
Lines changed: 61 additions & 55 deletions b/‎tutorials/text/usetex.py‎
Lines changed: 61 additions & 55 deletions
@@ -9,16 +9,16 @@
 its own TeX expression parser, layout engine, and fonts.  The layout engine
 is a fairly direct adaptation of the layout algorithms in Donald Knuth's
 TeX, so the quality is quite good (Matplotlib also provides a ``usetex``
-option for those who do want to call out to TeX to generate their text (see
+option for those who do want to call out to TeX to generate their text; see
 :doc:`/tutorials/text/usetex`).
 
 Any text element can use math text.  You should use raw strings (precede the
 quotes with an ``'r'``), and surround the math text with dollar signs ($), as
 in TeX. Regular text and mathtext can be interleaved within the same string.
 Mathtext can use DejaVu Sans (default), DejaVu Serif, the Computer Modern fonts
-(from (La)TeX), `STIX <http://www.stixfonts.org/>`_ fonts (with are designed
+(from (La)TeX), `STIX <http://www.stixfonts.org/>`_ fonts (which are designed
 to blend well with Times), or a Unicode font that you provide.  The mathtext
-font can be selected with the customization variable ``mathtext.fontset`` (see
+font can be selected via :rc:`mathtext.fontset` (see
 :doc:`/tutorials/introductory/customizing`)
 
 Here is a simple example::
 
@@ -1,7 +1,7 @@
 r"""
-*********************************************************
-Typesetting with XeLaTeX/LuaLaTeX via the ``pgf`` backend
-*********************************************************
+************************************************************
+Text rendering with XeLaTeX/LuaLaTeX via the ``pgf`` backend
+************************************************************
 
 Using the ``pgf`` backend, Matplotlib can export figures as pgf drawing
 commands that can be processed with pdflatex, xelatex or lualatex. XeLaTeX and
 
@@ -19,59 +19,54 @@
 itself (only LaTeX is supported).  The executables for these external
 dependencies must all be located on your :envvar:`PATH`.
 
-There are a couple of options to mention, which can be changed using
-:doc:`rc settings </tutorials/introductory/customizing>`. Here is an example
-matplotlibrc file::
-
-  font.family        : serif
-  font.serif         : Times, Palatino, New Century Schoolbook, Bookman, Computer Modern Roman
-  font.sans-serif    : Helvetica, Avant Garde, Computer Modern Sans Serif
-  font.cursive       : Zapf Chancery
-  font.monospace     : Courier, Computer Modern Typewriter
-
-  text.usetex        : true
-
-The first valid font in each family is the one that will be loaded. If the
-fonts are not specified, the Computer Modern fonts are used by default. All of
-the other fonts are Adobe fonts. Times and Palatino each have their own
-accompanying math fonts, while the other Adobe serif fonts make use of the
-Computer Modern math fonts. See the PSNFSS_ documentation for more details.
-
-To use LaTeX and select Helvetica as the default font, without editing
-matplotlibrc use::
-
-  import matplotlib.pyplot as plt
-  plt.rcParams.update({
-      "text.usetex": True,
-      "font.family": "sans-serif",
-      "font.sans-serif": ["Helvetica"]})
-  # for Palatino and other serif fonts use:
-  plt.rcParams.update({
-      "text.usetex": True,
-      "font.family": "serif",
-      "font.serif": ["Palatino"],
-  })
-  # It's also possible to use the reduced notation by directly setting font.family:
-  plt.rcParams.update({
-    "text.usetex": True,
-    "font.family": "Helvetica"
-  })
-
-Currently, the supported fonts are:
-
-================= ============================================================
-family            fonts
-================= ============================================================
-``'serif'``         ``'New Century Schoolbook'``, ``'Bookman'``, ``'Times'``,
-                    ``'Palatino'``, ``'Charter'``, ``'Computer Modern Roman'``
-
-``'sans-serif'``  ``'Helvetica'``, ``'Avant Garde'``, ``'Computer Modern
-                  Serif'``
-
-``'cursive'``     ``'Zapf Chancery'``
-
-``'monospace'``   ``'Courier'``, ``'Computer Modern Typewriter'``
-================= ============================================================
+Only a small number of font families (defined by the PSNFSS_ scheme) are
+supported.  They are listed here, with the corresponding LaTeX font selection
+commands and LaTeX packages, which are automatically used.
+
+=========================== =================================================
+generic family              fonts
+=========================== =================================================
+serif (``\rmfamily``)       Computer Modern Roman, Palatino (``mathpazo``),
+                            Times (``mathptmx``),  Bookman (``bookman``),
+                            New Century Schoolbook (``newcent``),
+                            Charter (``charter``)
+
+sans-serif (``\sffamily``)  Computer Modern Serif, Helvetica (``helvet``),
+                            Avant Garde (``avant``)
+
+cursive (``\rmfamily``)     Zapf Chancery (``chancery``)
+
+monospace (``\ttfamily``)   Computer Modern Typewriter, Courier (``courier``)
+=========================== =================================================
+
+The default font family (which does not require loading any LaTeX package) is
+Computer Modern.  All other families are Adobe fonts.  Times and Palatino each
+have their own accompanying math fonts, while the other Adobe serif fonts make
+use of the Computer Modern math fonts.
+
+To enable LaTeX and select a font, use e.g.::
+
+    plt.rcParams.update({
+        "text.usetex": True,
+        "font.family": "Helvetica"
+    })
+
+or equivalently, set your :doc:`matplotlibrc
+</tutorials/introductory/customizing>` to::
+
+    text.usetex : true
+    font.family : Helvetica
+
+It is also possible to instead set ``font.family`` to one of the generic family
+names and then configure the corresponding generic family; e.g.::
+
+    plt.rcParams.update({
+        "text.usetex": True,
+        "font.family": "sans-serif",
+        "font.sans-serif": "Helvetica",
+    })
+
+(this was the required approach until Matplotlib 3.5).
 
 Here is the standard example,
 :doc:`/gallery/text_labels_and_annotations/tex_demo`:
@@ -86,13 +81,23 @@
 Non-ASCII characters (e.g. the degree sign in the y-label above) are supported
 to the extent that they are supported by inputenc_.
 
+.. note::
+   For consistency with the non-usetex case, Matplotlib special-cases newlines,
+   so that single-newlines yield linebreaks (rather than being interpreted as
+   whitespace in standard LaTeX).
+
+   Matplotlib uses the underscore_ package so that underscores (``_``) are
+   printed "as-is" in text mode (rather than causing an error as in standard
+   LaTeX).  Underscores still introduce subscripts in math mode.
+
 .. note::
    Certain characters require special escaping in TeX, such as::
 
-     # $ % & ~ _ ^ \ { } \( \) \[ \]
+     # $ % & ~ ^ \ { } \( \) \[ \]
 
    Therefore, these characters will behave differently depending on
-   :rc:`text.usetex`.
+   :rc:`text.usetex`.  As noted above, underscores (``_``) do not require
+   escaping outside of math mode.
 
 PostScript options
 ==================
@@ -164,5 +169,6 @@
 .. _Poppler: https://poppler.freedesktop.org/
 .. _PSNFSS: http://www.ctan.org/tex-archive/macros/latex/required/psnfss/psnfss2e.pdf
 .. _PSfrag: https://ctan.org/pkg/psfrag
+.. _underscore: https://ctan.org/pkg/underscore
 .. _Xpdf: http://www.xpdfreader.com/
 """