Clarify family-names vs generic-families

Author: aitikgupta

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