Skip to content

Commit 74f68dc

Browse files
anntzeranntzer
committed
Tweak mathtext/tex docs.
- Fix typos/mismatched parentheses/markup in mathtext.py. - Make the title of pgf.py consistent with the title of usetex.py. - Prefer "modern" approach for setting fonts in usetex.py, but keep the old approach around (as the new API is only on Matplotlib 3.5). - Clarify non-standard tex settings.
1 parent 04051bd commit 74f68dc

File tree

3 files changed

+67
-61
lines changed

3 files changed

+67
-61
lines changed

‎tutorials/text/mathtext.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,16 @@
99
its own TeX expression parser, layout engine, and fonts. The layout engine
1010
is a fairly direct adaptation of the layout algorithms in Donald Knuth's
1111
TeX, so the quality is quite good (Matplotlib also provides a ``usetex``
12-
option for those who do want to call out to TeX to generate their text (see
12+
option for those who do want to call out to TeX to generate their text; see
1313
:doc:`/tutorials/text/usetex`).
1414
1515
Any text element can use math text. You should use raw strings (precede the
1616
quotes with an ``'r'``), and surround the math text with dollar signs ($), as
1717
in TeX. Regular text and mathtext can be interleaved within the same string.
1818
Mathtext can use DejaVu Sans (default), DejaVu Serif, the Computer Modern fonts
19-
(from (La)TeX), `STIX <http://www.stixfonts.org/>`_ fonts (with are designed
19+
(from (La)TeX), `STIX <http://www.stixfonts.org/>`_ fonts (which are designed
2020
to blend well with Times), or a Unicode font that you provide. The mathtext
21-
font can be selected with the customization variable ``mathtext.fontset`` (see
21+
font can be selected via :rc:`mathtext.fontset` (see
2222
:doc:`/tutorials/introductory/customizing`)
2323
2424
Here is a simple example::

‎tutorials/text/pgf.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
r"""
2-
*********************************************************
3-
Typesetting with XeLaTeX/LuaLaTeX via the ``pgf`` backend
4-
*********************************************************
2+
************************************************************
3+
Text rendering with XeLaTeX/LuaLaTeX via the ``pgf`` backend
4+
************************************************************
55
66
Using the ``pgf`` backend, Matplotlib can export figures as pgf drawing
77
commands that can be processed with pdflatex, xelatex or lualatex. XeLaTeX and

‎tutorials/text/usetex.py

Lines changed: 61 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -19,59 +19,54 @@
1919
itself (only LaTeX is supported). The executables for these external
2020
dependencies must all be located on your :envvar:`PATH`.
2121
22-
There are a couple of options to mention, which can be changed using
23-
:doc:`rc settings </tutorials/introductory/customizing>`. Here is an example
24-
matplotlibrc file::
25-
26-
font.family : serif
27-
font.serif : Times, Palatino, New Century Schoolbook, Bookman, Computer Modern Roman
28-
font.sans-serif : Helvetica, Avant Garde, Computer Modern Sans Serif
29-
font.cursive : Zapf Chancery
30-
font.monospace : Courier, Computer Modern Typewriter
31-
32-
text.usetex : true
33-
34-
The first valid font in each family is the one that will be loaded. If the
35-
fonts are not specified, the Computer Modern fonts are used by default. All of
36-
the other fonts are Adobe fonts. Times and Palatino each have their own
37-
accompanying math fonts, while the other Adobe serif fonts make use of the
38-
Computer Modern math fonts. See the PSNFSS_ documentation for more details.
39-
40-
To use LaTeX and select Helvetica as the default font, without editing
41-
matplotlibrc use::
42-
43-
import matplotlib.pyplot as plt
44-
plt.rcParams.update({
45-
"text.usetex": True,
46-
"font.family": "sans-serif",
47-
"font.sans-serif": ["Helvetica"]})
48-
# for Palatino and other serif fonts use:
49-
plt.rcParams.update({
50-
"text.usetex": True,
51-
"font.family": "serif",
52-
"font.serif": ["Palatino"],
53-
})
54-
# It's also possible to use the reduced notation by directly setting font.family:
55-
plt.rcParams.update({
56-
"text.usetex": True,
57-
"font.family": "Helvetica"
58-
})
59-
60-
Currently, the supported fonts are:
61-
62-
================= ============================================================
63-
family fonts
64-
================= ============================================================
65-
``'serif'`` ``'New Century Schoolbook'``, ``'Bookman'``, ``'Times'``,
66-
``'Palatino'``, ``'Charter'``, ``'Computer Modern Roman'``
67-
68-
``'sans-serif'`` ``'Helvetica'``, ``'Avant Garde'``, ``'Computer Modern
69-
Serif'``
70-
71-
``'cursive'`` ``'Zapf Chancery'``
72-
73-
``'monospace'`` ``'Courier'``, ``'Computer Modern Typewriter'``
74-
================= ============================================================
22+
Only a small number of font families (defined by the PSNFSS_ scheme) are
23+
supported. They are listed here, with the corresponding LaTeX font selection
24+
commands and LaTeX packages, which are automatically used.
25+
26+
=========================== =================================================
27+
generic family fonts
28+
=========================== =================================================
29+
serif (``\rmfamily``) Computer Modern Roman, Palatino (``mathpazo``),
30+
Times (``mathptmx``), Bookman (``bookman``),
31+
New Century Schoolbook (``newcent``),
32+
Charter (``charter``)
33+
34+
sans-serif (``\sffamily``) Computer Modern Serif, Helvetica (``helvet``),
35+
Avant Garde (``avant``)
36+
37+
cursive (``\rmfamily``) Zapf Chancery (``chancery``)
38+
39+
monospace (``\ttfamily``) Computer Modern Typewriter, Courier (``courier``)
40+
=========================== =================================================
41+
42+
The default font family (which does not require loading any LaTeX package) is
43+
Computer Modern. All other families are Adobe fonts. Times and Palatino each
44+
have their own accompanying math fonts, while the other Adobe serif fonts make
45+
use of the Computer Modern math fonts.
46+
47+
To enable LaTeX and select a font, use e.g.::
48+
49+
plt.rcParams.update({
50+
"text.usetex": True,
51+
"font.family": "Helvetica"
52+
})
53+
54+
or equivalently, set your :doc:`matplotlibrc
55+
</tutorials/introductory/customizing>` to::
56+
57+
text.usetex : true
58+
font.family : Helvetica
59+
60+
It is also possible to instead set ``font.family`` to one of the generic family
61+
names and then configure the corresponding generic family; e.g.::
62+
63+
plt.rcParams.update({
64+
"text.usetex": True,
65+
"font.family": "sans-serif",
66+
"font.sans-serif": "Helvetica",
67+
})
68+
69+
(this was the required approach until Matplotlib 3.5).
7570
7671
Here is the standard example,
7772
:doc:`/gallery/text_labels_and_annotations/tex_demo`:
@@ -86,13 +81,23 @@
8681
Non-ASCII characters (e.g. the degree sign in the y-label above) are supported
8782
to the extent that they are supported by inputenc_.
8883
84+
.. note::
85+
For consistency with the non-usetex case, Matplotlib special-cases newlines,
86+
so that single-newlines yield linebreaks (rather than being interpreted as
87+
whitespace in standard LaTeX).
88+
89+
Matplotlib uses the underscore_ package so that underscores (``_``) are
90+
printed "as-is" in text mode (rather than causing an error as in standard
91+
LaTeX). Underscores still introduce subscripts in math mode.
92+
8993
.. note::
9094
Certain characters require special escaping in TeX, such as::
9195
92-
# $ % & ~ _ ^ \ { } \( \) \[ \]
96+
# $ % & ~ ^ \ { } \( \) \[ \]
9397
9498
Therefore, these characters will behave differently depending on
95-
:rc:`text.usetex`.
99+
:rc:`text.usetex`. As noted above, underscores (``_``) do not require
100+
escaping outside of math mode.
96101
97102
PostScript options
98103
==================
@@ -164,5 +169,6 @@
164169
.. _Poppler: https://poppler.freedesktop.org/
165170
.. _PSNFSS: http://www.ctan.org/tex-archive/macros/latex/required/psnfss/psnfss2e.pdf
166171
.. _PSfrag: https://ctan.org/pkg/psfrag
172+
.. _underscore: https://ctan.org/pkg/underscore
167173
.. _Xpdf: http://www.xpdfreader.com/
168174
"""

0 commit comments

Comments
 (0)