Merge pull request #20346 from aitikgupta/font-docs

jklymak · web-flow · commit 02f2ea796840 · 2021-06-11T09:22:32.000-07:00
Clarify/Improve docs on family-names vs generic-families
diff --git a/examples/text_labels_and_annotations/font_family_rc_sgskip.py b/examples/text_labels_and_annotations/font_family_rc_sgskip.py
@@ -3,11 +3,17 @@
 Configuring the font family
 ===========================
 
-You can explicitly set which font family is picked up for a given font
-style (e.g., 'serif', 'sans-serif', or 'monospace').
+You can explicitly set which font family is picked up, either by specifying
+family names of fonts installed on user's system, or generic-families
+(e.g., 'serif', 'sans-serif', 'monospace', 'fantasy' or 'cursive'),
+or a combination of both.
+(see :doc:`font tutorial </tutorials/text/text_props>`)
 
-In the example below, we only allow one font family (Tahoma) for the
-sans-serif font style.  The default family is set with the font.family rcparam,
+In the example below, we are overriding the default sans-serif generic family
+to include a specific (Tahoma) font. (Note that the best way to achieve this
+would simply be to prepend 'Tahoma' in 'font.family')
+
+The default family is set with the font.family rcparam,
 e.g. ::
 
   rcParams['font.family'] = 'sans-serif'
diff --git a/tutorials/text/text_props.py b/tutorials/text/text_props.py
@@ -149,9 +149,9 @@
 # +---------------------+----------------------------------------------------+
 # | rcParam             | usage                                              |
 # +=====================+====================================================+
-# | ``'font.family'``   | List of either names of font or ``{'cursive',      |
-# |                     | 'fantasy', 'monospace', 'sans', 'sans serif',      |
-# |                     | 'sans-serif', 'serif'}``.                          |
+# | ``'font.family'``   | List of font families (installed on user's machine)|
+# |                     | and/or ``{'cursive', 'fantasy', 'monospace',       |
+# |                     | 'sans', 'sans serif', 'sans-serif', 'serif'}``.    |
 # |                     |                                                    |
 # +---------------------+----------------------------------------------------+
 # |  ``'font.style'``   | The default style, ex ``'normal'``,                |
@@ -174,13 +174,18 @@
 # |                     | this size.                                         |
 # +---------------------+----------------------------------------------------+
 #
-# The mapping between the family aliases (``{'cursive', 'fantasy',
-# 'monospace', 'sans', 'sans serif', 'sans-serif', 'serif'}``) and actual font names
+# Matplotlib can use font families installed on the user's computer, i.e.
+# Helvetica, Times, etc. Font families can also be specified with
+# generic-family aliases like (``{'cursive', 'fantasy', 'monospace',
+# 'sans', 'sans serif', 'sans-serif', 'serif'}``).
+#
+# The mapping between the generic family aliases and actual font families
+# (mentioned at :doc:`default rcParams </tutorials/introductory/customizing>`)
 # is controlled by the following rcParams:
 #
 #
 # +------------------------------------------+--------------------------------+
-# | family alias                             | rcParam with mappings          |
+# | CSS-based generic-family alias           | rcParam with mappings          |
 # +==========================================+================================+
 # | ``'serif'``                              | ``'font.serif'``               |
 # +------------------------------------------+--------------------------------+
@@ -194,7 +199,15 @@
 # +------------------------------------------+--------------------------------+
 #
 #
-# which are lists of font names.
+# If any of generic family names appear in ``'font.family'``, we replace that entry
+# by all the entries in the corresponding rcParam mapping.
+# For example: ::
+#
+#    matplotlib.rcParams['font.family'] = ['Family1', 'serif', 'Family2']
+#    matplotlib.rcParams['font.serif'] = ['SerifFamily1', 'SerifFamily2']
+#
+#    # This is effectively translated to:
+#    matplotlib.rcParams['font.family'] = ['Family1', 'SerifFamily1', 'SerifFamily2', 'Family2']
 #
 # Text with non-latin glyphs
 # ==========================
@@ -204,14 +217,26 @@
 # Korean, or Japanese.
 #
 # To set the default font to be one that supports the code points you
-# need, prepend the font name to ``'font.family'`` or the desired alias
-# lists ::
+# need, prepend the font name to ``'font.family'`` (recommended), or to the
+# desired alias lists. ::
+#
+#    # first method
+#    matplotlib.rcParams['font.family'] = ['Source Han Sans TW', 'sans-serif']
+#
+#    # second method
+#    matplotlib.rcParams['font.family'] = ['sans-serif']
+#    matplotlib.rcParams['sans-serif'] = ['Source Han Sans TW', ...]
+#
+# The generic family alias lists contain fonts that are either shipped
+# alongside Matplotlib (so they have 100% chance of being found), or fonts
+# which have a very high probability of being present in most systems.
 #
-#    matplotlib.rcParams['font.sans-serif'] = ['Source Han Sans TW', 'sans-serif']
+# A good practice when setting custom font families is to append
+# a generic-family to the font-family list as a last resort.
 #
-# or set it in your :file:`.matplotlibrc` file::
+# You can also set it in your :file:`.matplotlibrc` file::
 #
-#    font.sans-serif: Source Han Sans TW, Arial, sans-serif
+#    font.family: Source Han Sans TW, Arial, sans-serif
 #
 # To control the font used on per-artist basis use the *name*, *fontname* or
 # *fontproperties* keyword arguments documented :doc:`above
