Hopefully improving the wording in usage_faq.rst to make clear the differences between pyplot and pylab.

WeatherGod · WeatherGod · commit 5b5b3c9ed6cd · 2011-03-14T14:51:16.000-05:00
diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst
@@ -19,38 +19,47 @@ module in matplotlib.
 
 Pyplot provides a MATLAB-style state-machine interface to
 the underlying object-oriented plotting library in matplotlib.
+For example, calling a plotting function from pyplot will
+automatically create the necessary figure and axes to achieve
+the desired plot. Setting a title through pyplot will automatically
+set the title to the current axes object.
 
 Pylab combines the pyplot functionality (for plotting) with the numpy
 functionality (for mathematics and for working with arrays)
 in a single namespace, making that namespace
-(or environment) even more MATLAB-like.  This is what you get if
-you use the
+(or environment) even more MATLAB-like.
+For example, one can call the `sin` and `cos` functions just like
+you could in MATLAB, as well as having all the features of pyplot.
+
+The pyplot interface is generally preferred for non-interactive plotting
+(i.e., scripting). The pylab interface is generally preferred for interactive
+plotting in the python shell. Note that this is what you get if you use the
 *ipython* shell with the *-pylab* option, which imports everything
 from pylab and makes plotting fully interactive.
 
 We have been gradually converting the matplotlib examples
-from pure MATLAB-style, using "from pylab import \*", to a preferred
+from pure MATLAB-style (using "from pylab import \*"), to a preferred
 style in which pyplot is used for some convenience functions, either
 pyplot or the object-oriented style is used for the remainder of the
 plotting code, and numpy is used explicitly for numeric array operations.
 
-In this preferred style, the imports at the top are::
+In this preferred style, the imports at the top of your script are::
 
     import matplotlib.pyplot as plt
     import numpy as np
 
 Then one calls, for example, np.arange, np.zeros, np.pi, plt.figure,
 plt.plot, plt.show, etc.
 
-Example, pure MATLAB-style::
+Example in pure MATLAB-style::
 
     from pylab import *
     x = arange(0, 10, 0.2)
     y = sin(x)
     plot(x, y)
     show()
 
-Now in preferred style, but still using pyplot interface::
+Now in preferred style, using the pyplot interface::
 
     import matplotlib.pyplot as plt
     import numpy as np
@@ -59,7 +68,8 @@ Now in preferred style, but still using pyplot interface::
     plt.plot(x, y)
     plt.show()
 
-And using pyplot convenience functions, but object-orientation for the rest::
+For full control of your plots and more advanced usage, use the pyplot
+interface for creating figures, but then use object-orientation for the rest::
 
     import matplotlib.pyplot as plt
     import numpy as np
@@ -70,7 +80,7 @@ And using pyplot convenience functions, but object-orientation for the rest::
     ax.plot(x, y)
     plt.show()
 
-So, why do all the extra typing required as one moves away from the pure
+So, why all the extra typing required as one moves away from the pure
 MATLAB-style?  For very simple things like this example, the only
 advantage is educational: the wordier styles are more explicit, more
 clear as to where things come from and what is going on.  For more
