faq: move the backends section from installing to usage

efiring · efiring · commit 63a5c11fdcdb · 2011-06-04T11:15:26.000-10:00
If there is information about installing backends, then
that can be put in a new subsection of the installation faq;
but the subsection that I moved is much more relevant to mpl
usage than to installation.
diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -144,149 +144,6 @@ setupegg.py develop` command again to compile them.
 There is more information on :ref:`using git <using-git>` in
 the developer docs.
 
-Backends
-========
-
-.. _what-is-a-backend:
-
-What is a backend?
-------------------
-
-A lot of documentation on the website and in the mailing lists refers
-to the "backend" and many new users are confused by this term.
-matplotlib targets many different use cases and output formats.  Some
-people use matplotlib interactively from the python shell and have
-plotting windows pop up when they type commands.  Some people embed
-matplotlib into graphical user interfaces like wxpython or pygtk to
-build rich applications.  Others use matplotlib in batch scripts to
-generate postscript images from some numerical simulations, and still
-others in web application servers to dynamically serve up graphs.
-
-To support all of these use cases, matplotlib can target different
-outputs, and each of these capabilities is called a backend; the
-"frontend" is the user facing code, ie the plotting code, whereas the
-"backend" does all the hard work behind-the-scenes to make the
-figure.  There are two types of backends: user interface backends (for
-use in pygtk, wxpython, tkinter, qt, macosx, or fltk; also
-referred to as "interactive backends") and hardcopy backends to
-make image files (PNG, SVG, PDF, PS; also referred to as "non-interactive
-backends").
-
-There are a two primary ways to configure your backend.  One is to set
-the ``backend`` parameter in your ``matplotlibrc`` file (see
-:ref:`customizing-matplotlib`)::
-
-    backend : WXAgg   # use wxpython with antigrain (agg) rendering
-
-The other is to use the matplotlib :func:`~matplotlib.use` directive::
-
-    import matplotlib
-    matplotlib.use('PS')   # generate postscript output by default
-
-If you use the ``use`` directive, this must be done before importing
-:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
-
-.. note::
-   Backend name specifications are not case-sensitive; e.g., 'GTKAgg'
-   and 'gtkagg' are equivalent.
-
-With a typical installation of matplotlib, such as from a
-binary installer or a linux distribution package, a good default
-backend will already be set, allowing both interactive work and
-plotting from scripts, with output to the screen and/or to
-a file, so at least initially you will not need to use either of the
-two methods given above.
-
-If, however, you want to write graphical user interfaces, or a web
-application server (:ref:`howto-webapp`), or need a better
-understanding of what is going on, read on. To make things a little
-more customizable for graphical user interfaces, matplotlib separates
-the concept of the renderer (the thing that actually does the drawing)
-from the canvas (the place where the drawing goes).  The canonical
-renderer for user interfaces is ``Agg`` which uses the `Anti-Grain
-Geometry`_ C++ library to make a raster (pixel) image of the figure.
-All of the user interfaces except ``macosx`` can be used with
-agg rendering, eg
-``WXAgg``, ``GTKAgg``, ``QT4Agg``, ``TkAgg``.  In
-addition, some of the user interfaces support other rendering engines.
-For example, with GTK, you can also select GDK rendering (backend
-``GTK``) or Cairo rendering (backend ``GTKCairo``).
-
-For the rendering engines, one can also distinguish between `vector
-<http://en.wikipedia.org/wiki/Vector_graphics>`_ or `raster
-<http://en.wikipedia.org/wiki/Raster_graphics>`_ renderers.  Vector
-graphics languages issue drawing commands like "draw a line from this
-point to this point" and hence are scale free, and raster backends
-generate a pixel representation of the line whose accuracy depends on a
-DPI setting.
-
-Here is a summary of the matplotlib renderers (there is an eponymous
-backed for each; these are *non-interactive backends*, capable of
-writing to a file):
-
-=============   ============   ================================================
-Renderer        Filetypes      Description
-=============   ============   ================================================
-:term:`AGG`     :term:`png`    :term:`raster graphics` -- high quality images
-                               using the `Anti-Grain Geometry`_ engine
-PS              :term:`ps`     :term:`vector graphics` -- Postscript_ output
-                :term:`eps`
-PDF             :term:`pdf`    :term:`vector graphics` --
-                               `Portable Document Format`_
-SVG             :term:`svg`    :term:`vector graphics` --
-                               `Scalable Vector Graphics`_
-:term:`Cairo`   :term:`png`    :term:`vector graphics` --
-                :term:`ps`     `Cairo graphics`_
-                :term:`pdf`
-                :term:`svg`
-                ...
-:term:`GDK`     :term:`png`    :term:`raster graphics` --
-                :term:`jpg`    the `Gimp Drawing Kit`_
-                :term:`tiff`
-                ...
-=============   ============   ================================================
-
-And here are the user interfaces and renderer combinations supported;
-these are *interactive backends*, capable of displaying to the screen
-and of using appropriate renderers from the table above to write to
-a file:
-
-============   ================================================================
-Backend        Description
-============   ================================================================
-GTKAgg         Agg rendering to a :term:`GTK` canvas (requires PyGTK_)
-GTK            GDK rendering to a :term:`GTK` canvas (not recommended)
-               (requires PyGTK_)
-GTKCairo       Cairo rendering to a :term:`GTK` Canvas (requires PyGTK_)
-WXAgg          Agg rendering to to a :term:`wxWidgets` canvas
-               (requires wxPython_)
-WX             Native :term:`wxWidgets` drawing to a :term:`wxWidgets` Canvas
-               (not recommended) (requires wxPython_)
-TkAgg          Agg rendering to a :term:`Tk` canvas (requires TkInter_)
-QtAgg          Agg rendering to a :term:`Qt` canvas (requires PyQt_)
-               (not recommended; use Qt4Agg)
-Qt4Agg         Agg rendering to a :term:`Qt4` canvas (requires PyQt4_)
-FLTKAgg        Agg rendering to a :term:`FLTK` canvas (requires pyFLTK_)
-               (not widely used; consider TKAgg, GTKAgg, WXAgg, or
-               QT4Agg instead)
-macosx         Cocoa rendering in OSX windows
-               (presently lacks blocking show() behavior when matplotlib
-               is in non-interactive mode)
-============   ================================================================
-
-.. _`Anti-Grain Geometry`: http://www.antigrain.com/
-.. _Postscript: http://en.wikipedia.org/wiki/PostScript
-.. _`Portable Document Format`: http://en.wikipedia.org/wiki/Portable_Document_Format
-.. _`Scalable Vector Graphics`: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics
-.. _`Cairo graphics`: http://en.wikipedia.org/wiki/Cairo_(graphics)
-.. _`Gimp Drawing Kit`: http://en.wikipedia.org/wiki/GDK
-.. _PyGTK: http://www.pygtk.org
-.. _wxPython: http://www.wxpython.org/
-.. _TkInter: http://wiki.python.org/moin/TkInter
-.. _PyQt: http://www.riverbankcomputing.co.uk/software/pyqt/intro
-.. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/intro
-.. _pyFLTK: http://pyfltk.sourceforge.net
-
 
 OS-X questions
 ==============
diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst
@@ -146,4 +146,147 @@ complicated applications, this explicitness and clarity becomes
 increasingly valuable, and the richer and more complete object-oriented
 interface will likely make the program easier to write and maintain.
 
+Backends
+========
+
+.. _what-is-a-backend:
+
+What is a backend?
+------------------
+
+A lot of documentation on the website and in the mailing lists refers
+to the "backend" and many new users are confused by this term.
+matplotlib targets many different use cases and output formats.  Some
+people use matplotlib interactively from the python shell and have
+plotting windows pop up when they type commands.  Some people embed
+matplotlib into graphical user interfaces like wxpython or pygtk to
+build rich applications.  Others use matplotlib in batch scripts to
+generate postscript images from some numerical simulations, and still
+others in web application servers to dynamically serve up graphs.
+
+To support all of these use cases, matplotlib can target different
+outputs, and each of these capabilities is called a backend; the
+"frontend" is the user facing code, ie the plotting code, whereas the
+"backend" does all the hard work behind-the-scenes to make the
+figure.  There are two types of backends: user interface backends (for
+use in pygtk, wxpython, tkinter, qt, macosx, or fltk; also
+referred to as "interactive backends") and hardcopy backends to
+make image files (PNG, SVG, PDF, PS; also referred to as "non-interactive
+backends").
+
+There are a two primary ways to configure your backend.  One is to set
+the ``backend`` parameter in your ``matplotlibrc`` file (see
+:ref:`customizing-matplotlib`)::
+
+    backend : WXAgg   # use wxpython with antigrain (agg) rendering
+
+The other is to use the matplotlib :func:`~matplotlib.use` directive::
+
+    import matplotlib
+    matplotlib.use('PS')   # generate postscript output by default
+
+If you use the ``use`` directive, this must be done before importing
+:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
+
+.. note::
+   Backend name specifications are not case-sensitive; e.g., 'GTKAgg'
+   and 'gtkagg' are equivalent.
+
+With a typical installation of matplotlib, such as from a
+binary installer or a linux distribution package, a good default
+backend will already be set, allowing both interactive work and
+plotting from scripts, with output to the screen and/or to
+a file, so at least initially you will not need to use either of the
+two methods given above.
+
+If, however, you want to write graphical user interfaces, or a web
+application server (:ref:`howto-webapp`), or need a better
+understanding of what is going on, read on. To make things a little
+more customizable for graphical user interfaces, matplotlib separates
+the concept of the renderer (the thing that actually does the drawing)
+from the canvas (the place where the drawing goes).  The canonical
+renderer for user interfaces is ``Agg`` which uses the `Anti-Grain
+Geometry`_ C++ library to make a raster (pixel) image of the figure.
+All of the user interfaces except ``macosx`` can be used with
+agg rendering, eg
+``WXAgg``, ``GTKAgg``, ``QT4Agg``, ``TkAgg``.  In
+addition, some of the user interfaces support other rendering engines.
+For example, with GTK, you can also select GDK rendering (backend
+``GTK``) or Cairo rendering (backend ``GTKCairo``).
+
+For the rendering engines, one can also distinguish between `vector
+<http://en.wikipedia.org/wiki/Vector_graphics>`_ or `raster
+<http://en.wikipedia.org/wiki/Raster_graphics>`_ renderers.  Vector
+graphics languages issue drawing commands like "draw a line from this
+point to this point" and hence are scale free, and raster backends
+generate a pixel representation of the line whose accuracy depends on a
+DPI setting.
+
+Here is a summary of the matplotlib renderers (there is an eponymous
+backed for each; these are *non-interactive backends*, capable of
+writing to a file):
+
+=============   ============   ================================================
+Renderer        Filetypes      Description
+=============   ============   ================================================
+:term:`AGG`     :term:`png`    :term:`raster graphics` -- high quality images
+                               using the `Anti-Grain Geometry`_ engine
+PS              :term:`ps`     :term:`vector graphics` -- Postscript_ output
+                :term:`eps`
+PDF             :term:`pdf`    :term:`vector graphics` --
+                               `Portable Document Format`_
+SVG             :term:`svg`    :term:`vector graphics` --
+                               `Scalable Vector Graphics`_
+:term:`Cairo`   :term:`png`    :term:`vector graphics` --
+                :term:`ps`     `Cairo graphics`_
+                :term:`pdf`
+                :term:`svg`
+                ...
+:term:`GDK`     :term:`png`    :term:`raster graphics` --
+                :term:`jpg`    the `Gimp Drawing Kit`_
+                :term:`tiff`
+                ...
+=============   ============   ================================================
+
+And here are the user interfaces and renderer combinations supported;
+these are *interactive backends*, capable of displaying to the screen
+and of using appropriate renderers from the table above to write to
+a file:
+
+============   ================================================================
+Backend        Description
+============   ================================================================
+GTKAgg         Agg rendering to a :term:`GTK` canvas (requires PyGTK_)
+GTK            GDK rendering to a :term:`GTK` canvas (not recommended)
+               (requires PyGTK_)
+GTKCairo       Cairo rendering to a :term:`GTK` Canvas (requires PyGTK_)
+WXAgg          Agg rendering to to a :term:`wxWidgets` canvas
+               (requires wxPython_)
+WX             Native :term:`wxWidgets` drawing to a :term:`wxWidgets` Canvas
+               (not recommended) (requires wxPython_)
+TkAgg          Agg rendering to a :term:`Tk` canvas (requires TkInter_)
+QtAgg          Agg rendering to a :term:`Qt` canvas (requires PyQt_)
+               (not recommended; use Qt4Agg)
+Qt4Agg         Agg rendering to a :term:`Qt4` canvas (requires PyQt4_)
+FLTKAgg        Agg rendering to a :term:`FLTK` canvas (requires pyFLTK_)
+               (not widely used; consider TKAgg, GTKAgg, WXAgg, or
+               QT4Agg instead)
+macosx         Cocoa rendering in OSX windows
+               (presently lacks blocking show() behavior when matplotlib
+               is in non-interactive mode)
+============   ================================================================
+
+.. _`Anti-Grain Geometry`: http://www.antigrain.com/
+.. _Postscript: http://en.wikipedia.org/wiki/PostScript
+.. _`Portable Document Format`: http://en.wikipedia.org/wiki/Portable_Document_Format
+.. _`Scalable Vector Graphics`: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics
+.. _`Cairo graphics`: http://en.wikipedia.org/wiki/Cairo_(graphics)
+.. _`Gimp Drawing Kit`: http://en.wikipedia.org/wiki/GDK
+.. _PyGTK: http://www.pygtk.org
+.. _wxPython: http://www.wxpython.org/
+.. _TkInter: http://wiki.python.org/moin/TkInter
+.. _PyQt: http://www.riverbankcomputing.co.uk/software/pyqt/intro
+.. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/intro
+.. _pyFLTK: http://pyfltk.sourceforge.net
+
 
