Add an embryonic usage_faq.rst, based on a reply to a question on the list

efiring · efiring · commit 27edb7a17d17 · 2008-11-21T00:06:53.000Z
svn path=/trunk/matplotlib/; revision=6426
diff --git a/doc/faq/index.rst b/doc/faq/index.rst
@@ -15,6 +15,6 @@ The Matplotlib FAQ
    :maxdepth: 2
 
    installing_faq.rst
-   usage.rst
+   usage_faq.rst
    howto_faq.rst
    troubleshooting_faq.rst
diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst
@@ -0,0 +1,82 @@
+.. _usage-faq:
+
+***************
+Usage
+***************
+
+.. contents::
+   :backlinks: none
+
+.. _pylab:
+
+Matplotlib, pylab, and pyplot: how are they related?
+====================================================
+
+Matplotlib is the whole package; :mod:`pylab` is a module in matplotlib
+that gets
+installed alongside :mod:`matplotlib`; and :mod:`matplotlib.pyplot` is a
+module in matplotlib.
+
+Pyplot provides a Matlab-style state-machine interface to
+the underlying object-oriented plotting library in matplotlib.
+
+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
+*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
+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::
+
+    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::
+
+    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::
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    x = np.arange(0, 10, 0.2)
+    y = np.sin(x)
+    plt.plot(x, y)
+    plt.show()
+
+And using pyplot convenience functions, but object-orientation for the rest::
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    x = np.arange(0, 10, 0.2)
+    y = np.sin(x)
+    fig = plt.figure()
+    ax = fig.add_subplot(111)
+    ax.plot(x, y)
+    plt.show()
+
+So, why do 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
+complicated applications, the explicitness and clarity become
+increasingly valuable, and the richer and more complete object-oriented
+interface will likely make the program easier to write and maintain.
+
+
+
