added documentation on backend selection methods

Author: FlorianRhiem

CHANGELOG

@@ -1,3 +1,6 @@
+2014-10-27 Allowed selection of the backend using the `MPLBACKEND` environment
+           variable. Added documentation on backend selection methods.
+
 2014-09-27 Overhauled `colors.LightSource`.  Added `LightSource.hillshade` to
 	   allow the independent generation of illumination maps. Added new
 	   types of blending for creating more visually appealing shaded relief

doc/devel/coding_guide.rst

@@ -270,15 +270,20 @@ external backend via the ``module`` directive.  if
 
     backend : module://my_backend
 
-* with the use directive is your script::
 
-    import matplotlib
-    matplotlib.use('module://my_backend')
+* with the :envvar:`MPLBACKEND` environment variable::
+
+    > export MPLBACKEND="module://my_backend"
+    > python simple_plot.py
 
-* from the command shell with the -d flag::
+* from the command shell with the `-d` flag::
 
-    > python simple_plot.py -d module://my_backend
+    > python simple_plot.py -dmodule://my_backend
 
+* with the use directive is your script::
+
+    import matplotlib
+    matplotlib.use('module://my_backend')
 
 .. _sample-data:
 

doc/faq/environment_variables_faq.rst

@@ -30,6 +30,12 @@ Environment Variables
   used to find a base directory in which the :file:`matplotlib`
   subdirectory is created.
 
+.. envvar:: MPLBACKEND
+
+  This optional variable can be set to choose the matplotlib backend. Using the
+  `-d` command line parameter or the :func:`~matplotlib.use` function will
+  override this value. See :ref:`what-is-a-backend`.
+
 .. _setting-linux-osx-environment-variables:
 
 Setting environment variables in Linux and OS-X

doc/faq/usage_faq.rst

@@ -302,19 +302,37 @@ pygtk, wxpython, tkinter, qt4, or macosx; 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
+There are a four 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::
+Another way to do this is setting the :envvar:`MPLBACKEND` environment
+variable, either globally or for a single script::
+
+    > export MPLBACKEND="module://my_backend"
+    > python simple_plot.py
+
+To set the backend for a single script, you can alternatively use the `-d`
+command line argument::
+
+    > python script.py -dbackend
+
+You should be aware though that this might conflict with scripts which use the
+command line arguments.
+
+If your script depends on a specific backend you can 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`.
+:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`. Using this function will
+require a change in your code for users who would like to use a different
+backend. Therefore you should avoid explicitly calling ``use`` unless
+necessary.
 
 .. note::
    Backend name specifications are not case-sensitive; e.g., 'GTKAgg'
@@ -325,7 +343,7 @@ 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.
+methods given above.
 
 If, however, you want to write graphical user interfaces, or a web
 application server (:ref:`howto-webapp`), or need a better

doc/users/whats_new.rst

@@ -60,6 +60,13 @@ Added a :code:`pivot` kwarg to :func:`~mpl_toolkits.mplot3d.Axes3D.quiver`
 that controls the pivot point around which the quiver line rotates. This also
 determines the placement of the arrow head along the quiver line.
 
+New backend selection
+---------------------
+
+The environment variable :envvar:`MPLBACKEND` can now be used to set the
+matplotlib backend.
+
+
 .. _whats-new-1-4:
 
 new in matplotlib-1.4

lib/matplotlib/__init__.py

@@ -1379,12 +1379,11 @@ def tk_window_focus():
         # we don't want to assume all -d flags are backends, e.g., -debug
 else:
     # no backend selected from the command line, so we check the environment
-    # variable MPL_BACKEND
-    if 'MPL_BACKEND' in os.environ:
-        try:
-            use(os.environ['MPL_BACKEND'])
-        except (KeyError, ValueError):
-            pass
+    # variable MPLBACKEND
+    try:
+        use(os.environ['MPLBACKEND'])
+    except (KeyError, ValueError):
+        pass
 
 default_test_modules = [
     'matplotlib.tests.test_agg',