DOC: try better math

jklymak · jklymak · commit 04e096f78d1a · 2018-08-24T10:42:14.000-07:00
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -1,11 +1,11 @@
 """
 Builtin colormaps, colormap handling utilities, and the `ScalarMappable` mixin.
 
-  - See :doc:`/gallery/color/colormap_reference` for a list of builtin
+- See :doc:`/gallery/color/colormap_reference` for a list of builtin
     colormaps.
-  - See :doc:`/tutorials/colors/colormaps` for an in-depth discussion of
+- See :doc:`/tutorials/colors/colormaps` for an in-depth discussion of
     choosing colormaps.
-  - See :doc:`/tutorials/colors/colormap-manipulation` for an in-depth
+- See :doc:`/tutorials/colors/colormap-manipulation` for an in-depth
     discussion of how to manipulate colormaps.
 
 """
diff --git a/tutorials/colors/colormap-manipulation.py b/tutorials/colors/colormap-manipulation.py
@@ -55,8 +55,8 @@
 print('viridis(np.linspace(0, 1, 15))', viridis(np.linspace(0, 1, 15)))
 
 ##############################################################################
-# Creating a new ListedColormap
-# =============================
+# Creating ListedColormaps
+# ========================
 #
 # This is essential the inverse operation of the above where we supply a
 # Nx4 numpy array with all values between 0 and 1,
@@ -123,15 +123,14 @@ def plot_examples(cms):
 plot_examples([viridis, newcmp])
 
 ##############################################################################
-# LinearSegmented colormaps
-# =========================
+# Creating LinearSegmented colormaps
+# ==================================
 #
-# `.LinearSegmentedColormap` have an alternate way to specify colormaps that
-# specify anchor points for linear ramps for each of RGB, and optionally, alpha
-# (RGBA).
+# `.LinearSegmentedColormap` specify colormaps using anchor points
+#  that between which RGB(A) values are interpolated.
 #
-# The format to specify these colormaps is a bit complicated to allow
-# discontinuities at the anchor points.  First, with no discontinuities:
+# The format to specify these colormaps allows discontinuities at the anchor
+# points. First, with no discontinuities:
 
 cdict = {'red':   [[0.0,  0.0, 0.0],
                    [0.5,  1.0, 1.0],
@@ -161,14 +160,28 @@ def plot_linearmap(cdict):
 plot_linearmap(cdict)
 
 #############################################################################
-# However, consider the case where the third column is different than the
-# second.  The linear interpolation between red[i, 0] and red[i+1, 0] is
-# from red[i, 2] to red[i+1, 1].  This format allows us to have
-# discontinuities in the colormap at the anchor points; in this case
-# between 0 and 0.5, the linear interpolation goes from 0.3 to 1, and
-# between 0.5 and 1 it goes from 0.9 to 1.  Note that red[0, 1], and red[2, 2]
-# are both superfluous to the interpolation, which happens between the last
-# element of the first anchor and the first element of the second anchor.
+# In order to make a discontinuity at an anchor point, the third column is
+# different than the second.  The third column is the interpolation value
+# to the right of the anchor, and the second column the value to the left.
+# The linear interpolation between :math:`x_i=red[i, 0]`` and
+# :math:`x_{i+1} = red[i+1, 0]` is
+# from :math:`yright_{i} = red[i, 2]` to `yleft_{i+1} = red[i+1, 1]`,
+# where the matrix ``red`` is set up as:
+#
+# .. math::
+#
+#    \begin{pmatrix}
+#      \hdotsfor[]{3}
+#      x_i & yleft_i & yright_i \\
+#      x_{i+1} & yleft_{i+1} & yright_{i+1} \\
+#      \hdotsfor[]{3}
+#    \end{pmatrix}
+#
+# In the example below there is a discontiuity in red at 0.5.  The
+# interpolation between 0 and 0.5 goes from 0.3 to 1, and between 0.5 and 1
+# it goes from 0.9 to 1.  Note that red[0, 1], and red[2, 2] are both
+# superfluous to the interpolation because red[0, 1] is the value to the
+# left of 0, and red[2, 2] is the value to the right of 1.0.
 
 cdict['red'] = [[0.0,  0.0, 0.3],
                 [0.5,  1.0, 0.9],
