Better documentation for print_figure refactoring.

Author: pwuertz

lib/matplotlib/backend_bases.py

@@ -2018,7 +2018,11 @@ def get_supported_filetypes_grouped(cls):
             groupings[name].sort()
         return groupings
 
-    def _get_print_canvas(self, format):
+    def _get_output_canvas(self, format):
+        """Return a canvas that is suitable for saving figures to a specified
+        file format. If necessary, this function will switch to a registered
+        backend that supports the format.
+        """
         method_name = 'print_%s' % format
 
         # check if this canvas supports the requested format
@@ -2092,7 +2096,7 @@ def print_figure(self, filename, dpi=None, facecolor='w', edgecolor='w',
         format = format.lower()
 
         # get canvas object and print method for format
-        canvas = self._get_print_canvas(format)
+        canvas = self._get_output_canvas(format)
         print_method = getattr(canvas, 'print_%s' % format)
 
         if dpi is None:

lib/matplotlib/backends/backend_template.py

@@ -31,11 +31,19 @@
   import matplotlib
   matplotlib.use('module://my_backend')
 
-where my_backend.py is your module name.  Thus syntax is also
+where my_backend.py is your module name.  This syntax is also
 recognized in the rc file and in the -d argument in pylab, eg::
 
   python simple_plot.py -dmodule://my_backend
 
+If your backend implements support for saving figures (i.e. has a print_xyz()
+method) you can register it as the default handler for a given file type
+
+  from matplotlib.backend_bases import register_backend
+  register_backend('xyz', 'my_backend', 'XYZ File Format')
+  ...
+  plt.savefig("figure.xyz")
+
 The files that are most relevant to backend_writers are
 
   matplotlib/backends/backend_your_backend.py