Added significant information regarding the usage of the show() command.

WeatherGod · WeatherGod · commit 339705c98c50 · 2011-03-14T14:55:32.000-05:00
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -464,17 +464,43 @@ pyplot::
 Use :func:`~matplotlib.pyplot.show`
 ------------------------------------------
 
-The user interface backends need to start the GUI mainloop, and this
-is what :func:`~matplotlib.pyplot.show` does.  It tells matplotlib to
-raise all of the figure windows and start the mainloop.  Because the
-mainloop is blocking, you should only call this once per script, at
-the end.  If you are using matplotlib to generate images only and do
-not want a user interface window, you do not need to call ``show``  (see
-:ref:`howto-batch` and :ref:`what-is-a-backend`).
+When you want to view your plots on your display,
+the user interface backend will need to start the GUI mainloop.
+This is what :func:`~matplotlib.pyplot.show` does.  It tells
+matplotlib to raise all of the figure windows created so far and start
+the mainloop. Because this mainloop is blocking (i.e., script execution is
+paused), you should only call this once per script, at the end.  Script
+execution is resumed after the last window is closed.  Therefore, if you are
+using matplotlib to generate only images and do not want a user interface
+window, you do not need to call ``show``  (see :ref:`howto-batch` and
+:ref:`what-is-a-backend`).
 
+.. note::
+   Because closing a figure window invokes the destruction of its plotting
+   elements, you should call :func:`~matplotlib.pyplot.savefig` *before*
+   calling ``show`` if you wish to save the figure as well as view it.
+
+.. versionadded:: v1.0.0
+   ``show`` now starts the GUI mainloop only if it isn't already running.
+   Therefore, multiple calls to ``show`` are now allowed.
 
-Because it is expensive to draw, matplotlib does not want redraw the figure
-many times in a script such as the following::
+Having ``show`` block further execution of the script or the python
+interperator depends on whether matplotlib is set for interactive mode
+or not.  In non-interactive mode (the default setting), execution is paused
+until the last figure window is closed.  In interactive mode, the execution
+is not paused, which allows you to create additional figures (but the script
+won't finish until the last figure window is closed).
+
+.. note::
+   Support for interactive/non-interactive mode depends upon the backend.
+   Until version 1.0.0 (and subsequent fixes for 1.0.1), the behavior of
+   the interactive mode was not consistent across backends.
+   As of v1.0.1, only the macosx backend differs from other backends
+   because it does not support non-interactive mode.
+
+
+Because it is expensive to draw, you typically will not want matplotlib
+to redraw a figure many times in a script such as the following::
 
     plot([1,2,3])            # draw here ?
     xlabel('time')           # and here ?
@@ -483,24 +509,24 @@ many times in a script such as the following::
     show()
 
 
-It is *possible* to force matplotlib to draw after every command,
+However, it is *possible* to force matplotlib to draw after every command,
 which might be what you want when working interactively at the
 python console (see :ref:`mpl-shell`), but in a script you want to
-defer all drawing until the script has executed.  This is especially
+defer all drawing until the call to ``show``.  This is especially
 important for complex figures that take some time to draw.
 :func:`~matplotlib.pyplot.show` is designed to tell matplotlib that
 you're all done issuing commands and you want to draw the figure now.
 
 .. note::
 
-    :func:`~matplotlib.pyplot.show` should be called at most once per
-    script and it should be the last line of your script.  At that
-    point, the GUI takes control of the interpreter.  If you want to
-    force a figure draw, use :func:`~matplotlib.pyplot.draw` instead.
+    :func:`~matplotlib.pyplot.show` should typically only be called
+    at most once per script and it should be the last line of your script.
+    At that point, the GUI takes control of the interpreter.  If you want
+    to force a figure draw, use :func:`~matplotlib.pyplot.draw` instead.
 
-Many users are frustrated by show because they want it to be a
-blocking call that raises the figure, pauses the script until the
-figure is closed, and then allows the script to continue running until
+Many users are frustrated by ``show`` because they want it to be a
+blocking call that raises the figure, pauses the script until they
+close the figure, and then allow the script to continue running until
 the next figure is created and the next show is made.  Something like
 this::
 
@@ -511,7 +537,13 @@ this::
 
 This is not what show does and unfortunately, because doing blocking
 calls across user interfaces can be tricky, is currently unsupported,
-though we have made some progress towards supporting blocking events.
+though we have made significant progress towards supporting blocking events.
+
+.. versionadded:: v1.0.0
+   As noted earlier, this restriction has been relaxed to allow multiple
+   calls to ``show``.  In *most* backends, you can now expect to be
+   able to create new figures and raise them in a subsequent call to
+   ``show`` after closing the figures from a previous call to ``show``.
 
 
 .. _howto-contribute:
