Merge pull request #24876 from meeseeksmachine/auto-backport-of-pr-24873-on-v3.6.x

ksunden · web-flow · commit a886617b7847 · 2023-01-03T15:46:18.000-06:00
Backport PR #24873 on branch v3.6.x (Copy-edit fonts docs.)
diff --git a/doc/users/explain/fonts.rst b/doc/users/explain/fonts.rst
@@ -19,9 +19,9 @@ Fonts in PDF and PostScript
 ---------------------------
 
 Fonts have a long (and sometimes incompatible) history in computing, leading to
-different platforms supporting different types of fonts.  In practice, there
-are 3 types of font specifications Matplotlib supports (in addition to 'core
-fonts' in pdf which is explained later in the guide):
+different platforms supporting different types of fonts.  In practice,
+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
@@ -40,33 +40,35 @@ fonts' in pdf which is explained later in the guide):
      - Do not support font hinting
      - Hinting supported (virtual machine processes the "hints")
    * - Non-subsetted through Matplotlib
-     - Subsetted via external module `ttconv <https://github.com/sandflow/ttconv>`_
-     - Subsetted via external module `fonttools <https://github.com/fonttools/fonttools>`__
+     - Subsetted via external module ttconv
+     - Subsetted via external module `fontTools <https://github.com/fonttools/fonttools>`__
 
-NOTE: Adobe will disable support for authoring with Type 1 fonts in
-January 2023. `Read more here. <https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html>`_
+.. note::
 
+   Adobe disabled__ support for authoring with Type 1 fonts in January 2023.
+
+   __ https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html
 
 Other font specifications which Matplotlib supports:
 
 - Type 42 fonts (PS):
 
   - PostScript wrapper around TrueType fonts
   - 42 is the `Answer to Life, the Universe, and Everything! <https://en.wikipedia.org/wiki/Answer_to_Life,_the_Universe,_and_Everything>`_
-  - Matplotlib uses an external library called `fonttools <https://github.com/fonttools/fonttools>`__
+  - Matplotlib uses the external library `fontTools <https://github.com/fonttools/fonttools>`__
     to subset these types of fonts
 
 - OpenType fonts:
 
   - OpenType is a new standard for digital type fonts, developed jointly by
     Adobe and Microsoft
   - Generally contain a much larger character set!
-  - Limited Support with Matplotlib
+  - Limited support with Matplotlib
 
-Font Subsetting
+Font subsetting
 ~~~~~~~~~~~~~~~
 
-The PDF and PostScript formats support embedding fonts in files allowing the
+The PDF and PostScript formats support embedding fonts in files, allowing the
 display program to correctly render the text, independent of what fonts are
 installed on the viewer's computer and without the need to pre-rasterize the text.
 This ensures that if the output is zoomed or resized the text does not become
@@ -79,10 +81,9 @@ 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 <https://github.com/sandflow/ttconv>`_.
-
-Currently Type 3, Type 42, and TrueType fonts are subseted.  Type 1 fonts are not.
+of ttconv.
 
+Currently Type 3, Type 42, and TrueType fonts are subsetted.  Type 1 fonts are not.
 
 Core Fonts
 ~~~~~~~~~~
@@ -91,11 +92,11 @@ In addition to the ability to embed fonts, as part of the `PostScript
 <https://en.wikipedia.org/wiki/PostScript_fonts#Core_Font_Set>`_ and `PDF
 specification
 <https://docs.oracle.com/cd/E96927_01/TSG/FAQ/What%20are%20the%2014%20base%20fonts%20distributed%20with%20Acroba.html>`_
-there are 14 Core Font that compliant viewers must ensure are available.  If
+there are 14 Core Fonts that compliant viewers must ensure are available.  If
 you restrict your document to only these fonts you do not have to embed any
 font information in the document but still get vector text.
 
-This is especially helpful to generate *really lightweight* documents.::
+This is especially helpful to generate *really lightweight* documents::
 
     # trigger core fonts for PDF backend
     plt.rcParams["pdf.use14corefonts"] = True
@@ -109,7 +110,6 @@ This is especially helpful to generate *really lightweight* documents.::
     fig.savefig("AFM_PDF.pdf", format="pdf")
     fig.savefig("AFM_PS.ps", format="ps)
 
-
 Fonts in SVG
 ------------
 
@@ -118,12 +118,11 @@ Text can output to SVG in two ways controlled by :rc:`svg.fonttype`:
 - as a path (``'path'``) in the SVG
 - as string in the SVG with font styling on the element (``'none'``)
 
-
 When saving via ``'path'`` Matplotlib will compute the path of the glyphs used
-as vector paths and write those to the output.  The advantage of this is that
-the SVG will look the same on all computers independent of what fonts are
+as vector paths and write those to the output.  The advantage of doing so is
+that the SVG will look the same on all computers independent of what fonts are
 installed.  However the text will not be editable after the fact.
-In contrast saving with ``'none'`` will result in smaller files and the
+In contrast, saving with ``'none'`` will result in smaller files and the
 text will appear directly in the markup.  However, the appearance may vary
 based on the SVG viewer and what fonts are available.
 
@@ -135,11 +134,10 @@ To output text to raster formats via Agg, Matplotlib relies on `FreeType
 changes between FreeType versions we pin to a specific version for our image
 comparison tests.
 
-
 How Matplotlib selects fonts
 ----------------------------
 
-Internally using a Font in Matplotlib is a three step process:
+Internally, using a font in Matplotlib is a three step process:
 
 1. a `.FontProperties` object is created (explicitly or implicitly)
 2. based on the `.FontProperties` object the methods on `.FontManager` are used
@@ -153,16 +151,16 @@ specified by the `CSS1 Specifications
 <http://www.w3.org/TR/1998/REC-CSS2-19980512/>`_ which is used by web browsers.
 This algorithm takes into account the font family name (e.g. "Arial", "Noto
 Sans CJK", "Hack", ...), the size, style, and weight.  In addition to family
-names that map directly to fonts there are five "generic font family names" (
-serif, monospace, fantasy, cursive, and sans-serif) that will internally be
+names that map directly to fonts there are five "generic font family names"
+(serif, monospace, fantasy, cursive, and sans-serif) that will internally be
 mapped to any one of a set of fonts.
 
 Currently the public API for doing step 2 is `.FontManager.findfont` (and that
 method on the global `.FontManager` instance is aliased at the module level as
 `.font_manager.findfont`), which will only find a single font and return the absolute
 path to the font on the filesystem.
 
-Font Fallback
+Font fallback
 -------------
 
 There is no font that covers the entire Unicode space thus it is possible for the
@@ -173,7 +171,6 @@ same `.Text` instance (as a web browser does).  As of Matplotlib 3.6 the Agg,
 SVG, PDF, and PS backends will "fallback" through multiple fonts in a single
 `.Text` instance:
 
-
 .. plot::
    :include-source:
    :caption: The string "There are 几个汉字 in between!" rendered with 2 fonts.
@@ -185,7 +182,6 @@ SVG, PDF, and PS backends will "fallback" through multiple fonts in a single
        ha='center'
    )
 
-
 Internally this is implemented by setting The "font family" on
 `.FontProperties` objects to a list of font families.  A (currently)
 private API extracts a list of paths to all of the fonts found and then
