gitcheng
diff --git a/‎doc/api/api_changes.rst
Lines changed: 76 additions & 61 deletions b/‎doc/api/api_changes.rst
Lines changed: 76 additions & 61 deletions
@@ -17,18 +17,8 @@ For new features that were added to matplotlib, please see
 Changes in 1.3.x
 ================
 
-* Data limits on a plot now start from a point of having "null"
-  limits, rather than limits in the range (0, 1).  This has an effect
-  on artists that only control limits in one direction, such as
-  `axvline` and `axhline`, since their limits will not longer also
-  include the range (0, 1).  This fixes some problems where the
-  computed limits would be dependent on the order in which artists
-  were added to the axes.
-
-* On Linux, the user-specific `matplotlibrc` configuration file is now
-  located in `~/.config/matplotlib/matplotlibrc` to conform to the
-  `XDG Base Directory Specification
-  <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
+Code removal
+------------
 
 * The following items that were deprecated in version 1.2 or earlier
   have now been removed completely.
@@ -77,6 +67,9 @@ Changes in 1.3.x
     - `widgets.HorizontalSpanSelector` has been removed.  Use
       `widgets.SpanSelector` instead.
 
+Code deprecation
+----------------
+
 * The CocoaAgg backend has been deprecated, with the possibility for
   deletion or resurrection in a future release.
 
@@ -96,6 +89,47 @@ Changes in 1.3.x
     - `points_in_path` -> `path.Path.contains_points`
     - `clip_path_to_rect` -> `path.Path.clip_to_bbox`
 
+* `matplotlib.colors.normalize` and `matplotlib.colors.no_norm` have
+  been deprecated in favour of `matplotlib.colors.Normalize` and
+  `matplotlib.colors.NoNorm` respectively.
+
+* The `ScalarMappable` class' `set_colorbar` is now
+  deprecated. Instead, the
+  :attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should be
+  used.  In previous matplotlib versions this attribute was an
+  undocumented tuple of ``(colorbar_instance, colorbar_axes)`` but is
+  now just ``colorbar_instance``. To get the colorbar axes it is
+  possible to just use the
+  :attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar
+  instance.
+
+* The `~matplotlib.mpl` module is now deprecated. Those who relied on this
+  module should transition to simply using ``import matplotlib as mpl``.
+
+Code changes
+------------
+
+* :class:`~matplotlib.patches.Patch` now fully supports using RGBA values for
+  its ``facecolor`` and ``edgecolor`` attributes, which enables faces and
+  edges to have different alpha values. If the
+  :class:`~matplotlib.patches.Patch` object's ``alpha`` attribute is set to
+  anything other than ``None``, that value will override any alpha-channel
+  value in both the face and edge colors. Previously, if
+  :class:`~matplotlib.patches.Patch` had ``alpha=None``, the alpha component
+  of ``edgecolor`` would be applied to both the edge and face.
+
+* The optional ``isRGB`` argument to
+  :meth:`~matplotlib.backend_bases.GraphicsContextBase.set_foreground` (and
+  the other GraphicsContext classes that descend from it) has been renamed to
+  ``isRGBA``, and should now only be set to ``True`` if the ``fg`` color
+  argument is known to be an RGBA tuple.
+
+* For :class:`~matplotlib.patches.Patch`, the ``capstyle`` used is now
+  ``butt``, to be consistent with the default for most other objects, and to
+  avoid problems with non-solid ``linestyle`` appearing solid when using a
+  large ``linewidth``. Previously, :class:`~matplotlib.patches.Patch` used
+  ``capstyle='projecting'``.
+
 * `Path` objects can now be marked as `readonly` by passing
   `readonly=True` to its constructor.  The built-in path singletons,
   obtained through `Path.unit*` class methods return readonly paths.
@@ -112,46 +146,33 @@ Changes in 1.3.x
   Deep copying a `Path` always creates an editable (i.e. non-readonly)
   `Path`.
 
-* matplotlib.colors.normalize and matplotlib.colors.no_norm have been
-  deprecated in favour of matplotlib.colors.Normalize and
-  matplotlib.colors.NoNorm respectively.
-
-* The `font.*` rcParams now affect only text objects created after the
-  rcParam has been set, and will not retroactively affect already
-  existing text objects.  This brings their behavior in line with most
-  other rcParams.
+* The list at ``Path.NUM_VERTICES`` was replaced by a dictionary mapping
+  Path codes to the number of expected vertices at
+  :attr:`~matplotlib.path.Path.NUM_VERTICES_FOR_CODE`.
 
 * To support XKCD style plots, the :func:`matplotlib.path.cleanup_path`
   method's signature was updated to require a sketch argument. Users of
   :func:`matplotlib.path.cleanup_path` are encouraged to use the new
   :meth:`~matplotlib.path.Path.cleaned` Path method.
 
-* The list at ``Path.NUM_VERTICES`` was replaced by a dictionary mapping
-  Path codes to the number of expected vertices at
-  :attr:`~matplotlib.path.Path.NUM_VERTICES_FOR_CODE`.
+* Data limits on a plot now start from a state of having "null"
+  limits, rather than limits in the range (0, 1).  This has an effect
+  on artists that only control limits in one direction, such as
+  `axvline` and `axhline`, since their limits will not longer also
+  include the range (0, 1).  This fixes some problems where the
+  computed limits would be dependent on the order in which artists
+  were added to the axes.
 
 * Fixed a bug in setting the position for the right/top spine with data
   position type. Previously, it would draw the right or top spine at
   +1 data offset.
 
-* The ScalarMappable class' set_colorbar is now deprecated. Instead, the
-  :attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should be used.
-  In previous matplotlib versions this attribute was an undocumented tuple
-  of ``(colorbar_instance, colorbar_axes)`` but is now just
-  ``colorbar_instance``. To get the colorbar axes it is possible to just use
-  the :attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar
-  isntance.
-
-* In :class:`~matplotlib.patches.FancyArrow`, the default arrow head width,
-  ``head_width``, has been made larger to produce a visible arrow head. The new
-  value of this kwarg is ``head_width = 20 * width``.
-
-* Removed call of :meth:`~matplotlib.axes.Axes.grid` in
-  :meth:`~matplotlib.pyplot.plotfile`. To draw the axes grid, set the
-  ``axes.grid`` rcParam to *True*, or explicitly call
-  :meth:`~matplotlib.axes.Axes.grid`.
+* In :class:`~matplotlib.patches.FancyArrow`, the default arrow head
+  width, ``head_width``, has been made larger to produce a visible
+  arrow head. The new value of this kwarg is ``head_width = 20 *
+  width``.
 
-* It is now posible to provide ``number of levels + 1`` colors in the case of
+* It is now possible to provide ``number of levels + 1`` colors in the case of
   `extend='both'` for contourf (or just ``number of levels`` colors for an
   extend value ``min`` or ``max``) such that the resulting colormap's
   ``set_under`` and ``set_over`` are defined appropriately. Any other number
@@ -164,9 +185,6 @@ Changes in 1.3.x
   :class:`~matplotlib.colorbar.ColorbarBase` allows one to control the shape
   of colorbar extensions.
 
-* The `~matplotlib.mpl` module is now deprecated. Those who relied on this
-  module should transition to simply using ``import matplotlib as mpl``.
-
 * The extension of :class:`~matplotlib.widgets.MultiCursor` to both vertical
   (default) and/or horizontal cursor implied that ``self.line`` is replaced
   by ``self.vline`` for vertical cursors lines and ``self.hline`` is added
@@ -179,26 +197,23 @@ Changes in 1.3.x
 * The :func:`matplotlib.cbook.check_output` function has been moved to
   :func:`matplotlib.compat.subprocess`.
 
-* :class:`~matplotlib.patches.Patch` now fully supports using RGBA values for
-  its ``facecolor`` and ``edgecolor`` attributes, which enables faces and
-  edges to have different alpha values. If the
-  :class:`~matplotlib.patches.Patch` object's ``alpha`` attribute is set to
-  anything other than ``None``, that value will override any alpha-channel
-  value in both the face and edge colors. Previously, if
-  :class:`~matplotlib.patches.Patch` had ``alpha=None``, the alpha component
-  of ``edgecolor`` would be applied to both the edge and face.
+Configuration and rcParams
+--------------------------
 
-* The optional ``isRGB`` argument to
-  :meth:`~matplotlib.backend_bases.GraphicsContextBase.set_foreground` (and
-  the other GraphicsContext classes that descend from it) has been renamed to
-  ``isRGBA``, and should now only be set to ``True`` if the ``fg`` color
-  argument is known to be an RGBA tuple.
+* On Linux, the user-specific `matplotlibrc` configuration file is now
+  located in `~/.config/matplotlib/matplotlibrc` to conform to the
+  `XDG Base Directory Specification
+  <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
 
-* For :class:`~matplotlib.patches.Patch`, the ``capstyle`` used is now
-  ``butt``, to be consistent with the default for most other objects, and to
-  avoid problems with non-solid ``linestyle`` appearing solid when using a
-  large ``linewidth``. Previously, :class:`~matplotlib.patches.Patch` used
-  ``capstyle='projecting'``.
+* The `font.*` rcParams now affect only text objects created after the
+  rcParam has been set, and will not retroactively affect already
+  existing text objects.  This brings their behavior in line with most
+  other rcParams.
+
+* Removed call of :meth:`~matplotlib.axes.Axes.grid` in
+  :meth:`~matplotlib.pyplot.plotfile`. To draw the axes grid, set the
+  ``axes.grid`` rcParam to *True*, or explicitly call
+  :meth:`~matplotlib.axes.Axes.grid`.
 
 Changes in 1.2.x
 ================