Skip to content

Update font-related documentation #30150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 11, 2025
+31 −28
Merged

Update font-related documentation #30150

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
08cdd1a
Update font-related documentation
jkseppan Jun 7, 2025
c3ed0c9
Update galleries/users_explain/text/fonts.py
jkseppan Jun 11, 2025
153e254
Update galleries/users_explain/text/fonts.py
jkseppan Jun 11, 2025
867cf9f
Update galleries/users_explain/text/fonts.py
jkseppan Jun 11, 2025
2da9307
Update galleries/users_explain/text/fonts.py
jkseppan Jun 11, 2025
b2e6451
Reword paragraph on subsetting
jkseppan Jun 11, 2025
dfab321
Realign grid table
jkseppan Jun 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 31 additions & 28 deletions galleries/users_explain/text/fonts.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,30 +27,35 @@
Matplotlib supports three font specifications (in addition to pdf 'core fonts',
which are explained later in the guide):

.. list-table:: Type of Fonts
:header-rows: 1

* - Type 1 (PDF)
- Type 3 (PDF/PS)
- TrueType (PDF)
* - One of the oldest types, introduced by Adobe
- Similar to Type 1 in terms of introduction
- Newer than previous types, used commonly today, introduced by Apple
* - Restricted subset of PostScript, charstrings are in bytecode
- Full PostScript language, allows embedding arbitrary code
(in theory, even render fractals when rasterizing!)
- Include a virtual machine that can execute code!
* - These fonts support font hinting
- Do not support font hinting
- Hinting supported (virtual machine processes the "hints")
* - Non-subsetted through Matplotlib
- Subsetted via external module ttconv
- Subsetted via external module
`fontTools <https://github.com/fonttools/fonttools>`__
.. table:: Type of Fonts

+--------------------------+----------------------------+----------------------------+
| Type 1 (PDF with usetex) | Type 3 (PDF/PS) | TrueType (PDF) |
+==========================+============================+============================+
| One of the oldest types, | Similar to Type 1 in | Newer than previous types, |
| introduced by Adobe | terms of introduction | used commonly today, |
| | | introduced by Apple |
+--------------------------+----------------------------+----------------------------+
| Restricted subset of | Full PostScript language, | Includes a virtual machine |
| PostScript, charstrings | allows embedding arbitrary | that can execute code! |
| are in bytecode | code (in theory, even | |
| | render fractals when | |
| | rasterizing!) | |
+--------------------------+----------------------------+----------------------------+
| Supports font | Does not support font | Supports font hinting |
| hinting | hinting | (virtual machine processes |
| | | the "hints") |
+--------------------------+----------------------------+----------------------------+
| Subsetted by code in | Subsetted via external module |
| `matplotlib._type1font` | `fontTools <https://github.com/fonttools/fonttools>`__ |
+--------------------------+----------------------------+----------------------------+

.. note::

Adobe disabled__ support for authoring with Type 1 fonts in January 2023.
Matplotlib uses Type 1 fonts for compatibility with TeX; when the usetex
feature is used with the PDF backend, Matplotlib reads the fonts used by
the TeX engine, which are usually Type 1.

__ https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html

Expand Down Expand Up @@ -83,14 +88,12 @@
files, particularly with fonts with many glyphs such as those that support CJK
(Chinese/Japanese/Korean).

The solution to this problem is to subset the fonts used in the document and
only embed the glyphs actually used. This gets both vector text and small
files sizes. Computing the subset of the font required and writing the new
(reduced) font are both complex problem and thus Matplotlib relies on
`fontTools <https://fonttools.readthedocs.io/en/latest/>`__ and a vendored fork
of ttconv.

Currently Type 3, Type 42, and TrueType fonts are subsetted. Type 1 fonts are not.
To keep the output size reasonable while using vector fonts,
Matplotlib embeds only the glyphs that are actually used in the document.
This is known as font subsetting.
Computing the font subset and writing the reduced font are both complex problems,
which Matplotlib solves in most cases by using the
`fontTools <https://fonttools.readthedocs.io/en/latest/>`__ library.

Core Fonts
^^^^^^^^^^
Expand Down