Backport PR #27017: DOC: clarify usetex versus mathtext

timhoffm · meeseeksmachine · commit 1e7d7f5f1d08 · 2023-10-08T16:13:27.000Z
diff --git a/doc/users/prev_whats_new/whats_new_3.8.0.rst b/doc/users/prev_whats_new/whats_new_3.8.0.rst
@@ -327,6 +327,10 @@ This allows users to set the location of the legend in a more flexible and consi
 Mathtext improvements
 =====================
 
+Improvements are to Mathtext, Matplotlib's native TeX-like mathematics parser
+(see :ref:`mathtext`, not to be confused with Matplotlib using LaTeX directly:
+:ref:`usetex`).
+
 Boldsymbol mathtext command ``\boldsymbol``
 -------------------------------------------
 
diff --git a/galleries/users_explain/text/mathtext.py b/galleries/users_explain/text/mathtext.py
@@ -8,11 +8,15 @@
 ================================
 
 Matplotlib implements a lightweight TeX expression parser and layout engine and
-*Mathtext* is the subset of Tex markup that this engine supports. Any string can
-be processed as Mathtext by placing the string inside a pair of dollar signs
-``'$'``. Mathtext often contains many backslashes ``'\'``; so that the backslashes
-do not need to be escaped, Mathtext is often written using raw strings. For
-example:
+*Mathtext* is the subset of Tex markup that this engine supports. Note that
+Matplotlib can also render all text directly using TeX if :rc:`text.usetex` is
+*True*; see :ref:`usetex` for more details.   Mathtext support is available
+if :rc:`text.usetex` is *False*.
+
+Any string can be processed as Mathtext by placing the string inside a pair of
+dollar signs ``'$'``. Mathtext often contains many backslashes ``'\'``; so that
+the backslashes do not need to be escaped, Mathtext is often written using raw
+strings. For example:
 """
 
 import matplotlib.pyplot as plt
