@@ -11,6 +11,20 @@ help figure out possible sources of the changes you are experiencing.
 For new features that were added to matplotlib, please see
 :ref:`whats-new`.
 
+Changes in 1.2.x
+================
+* Use of :func:`matplotlib.projections.projection_factory` is now deprecated
+  in favour of axes class identification using 
+  :func:`matplotlib.projections.process_projection_requirements` followed by 
+  direct axes class invocation (at the time of writing, this is done by 
+  :meth:`matplotlib.figure.Figure.add_axes`, 
+  :meth:`matplotlib.figure.Figure.add_subplot` and 
+  :meth:`matplotlib.figure.Figure.gca`. 
+  This change means that third party objects can expose themselves as 
+  matplotlib axes by providing a ``_as_mpl_axes`` method (see 
+  :ref:`adding-new-scales` for more detail).
+
+
 Changes in 1.1.x
 ================
 
 
@@ -71,8 +71,9 @@ in :mod:`matplotlib.scale` that may be used as starting points.
 Creating a new projection
 =========================
 
-Adding a new projection consists of defining a subclass of
-:class:`matplotlib.axes.Axes`, that includes the following elements:
+Adding a new projection consists of defining a projection axes which
+subclasses :class:`matplotlib.axes.Axes` and includes the following 
+elements:
 
   - A transformation from data coordinates into display coordinates.
 
@@ -98,11 +99,28 @@ Adding a new projection consists of defining a subclass of
   - Set up interactive panning and zooming.  This is left as an
     "advanced" feature left to the reader, but there is an example of
     this for polar plots in :mod:`matplotlib.projections.polar`.
-
+    
   - Any additional methods for additional convenience or features.
 
-Once the class is defined, it must be registered with matplotlib
-so that the user can select it.
+Once the projection axes is defined, it can be used in one of two ways:
+
+  - By defining the class attribute ``NAME``, the projection axes can be 
+    registered with :func:`matplotlib.projections.register_projection` 
+    and subsequently simply invoked by name::  
+    
+        plt.axes(projection=NAME)
+    
+  - For more complex, parameterisable projections, a generic "projection"
+    object may be defined which includes the method ``_as_mpl_axes``.
+    ``_as_mpl_axes`` should take no arguments and return the projection's
+    axes subclass and a dictionary of additional arguments to pass to the
+    subclass' ``__init__`` method.  Subsequently a parameterised projection
+    can be initialised with::
+    
+        plt.axes(projection=MyProjection(param1=param1_value))
+        
+    where MyProjection is an object which implements a ``_as_mpl_axes`` method.
+
 
 A full-fledged and heavily annotated example is in
 :file:`examples/api/custom_projection_example.py`.  The polar plot
 
@@ -954,15 +954,11 @@ def hold(self, b=None):
         Set the hold state.  If *hold* is *None* (default), toggle the
         *hold* state.  Else set the *hold* state to boolean value *b*.
 
-        Examples:
-
-        * toggle hold:
-          >>> hold()
-        * turn hold on:
-          >>> hold(True)
-        * turn hold off
-          >>> hold(False)
-
+        Examples::
+          
+          hold()      # toggle hold
+          hold(True)  # turn hold on
+          hold(False) # turn hold off
 
         When hold is True, subsequent plot commands will be added to
         the current axes.  When hold is False, the current axes and
@@ -3483,12 +3479,11 @@ def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs):
         Return value is a :class:`matplotlib.patches.Polygon`
         instance.
 
-        Examples:
-
-        * draw a gray rectangle from *y* = 0.25-0.75 that spans the
-          horizontal extent of the axes
+        Examples::
 
-            >>> axhspan(0.25, 0.75, facecolor='0.5', alpha=0.5)
+            # draw a gray rectangle from *y* = 0.25-0.75 that spans the
+            # horizontal extent of the axes
+            axhspan(0.25, 0.75, facecolor='0.5', alpha=0.5)
 
         Valid kwargs are :class:`~matplotlib.patches.Polygon` properties:
 
@@ -3539,12 +3534,11 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
         Return value is the :class:`matplotlib.patches.Polygon`
         instance.
 
-        Examples:
-
-        * draw a vertical green translucent rectangle from x=1.25 to 1.55 that
-          spans the yrange of the axes
+        Examples::
 
-            >>> axvspan(1.25, 1.55, facecolor='g', alpha=0.5)
+            # draw a vertical green translucent rectangle from x=1.25 to 1.55
+            # that spans the yrange of the axes
+            axvspan(1.25, 1.55, facecolor='g', alpha=0.5)
 
         Valid kwargs are :class:`~matplotlib.patches.Polygon`
         properties:
@@ -6927,7 +6921,7 @@ def pcolor(self, *args, **kwargs):
           y = np.arange(3)
           X, Y = meshgrid(x,y)
 
-        is equivalent to:
+        is equivalent to::
 
           X = array([[0, 1, 2, 3, 4],
                      [0, 1, 2, 3, 4],
@@ -7467,11 +7461,11 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None,
         """
         call signature::
 
-          def hist(x, bins=10, range=None, normed=False, weights=None,
+          hist(x, bins=10, range=None, normed=False, weights=None,
                  cumulative=False, bottom=None, histtype='bar', align='mid',
                  orientation='vertical', rwidth=None, log=False,
                  color=None, label=None,
-                 **kwargs):
+                 **kwargs)
 
         Compute and draw the histogram of *x*. The return value is a
         tuple (*n*, *bins*, *patches*) or ([*n0*, *n1*, ...], *bins*,