faq updates

jdh2358 · jdh2358 · commit ebe6c5f5baab · 2008-05-30T20:05:57.000Z
svn path=/trunk/matplotlib/; revision=5336
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -0,0 +1,61 @@
+*****
+HOWTO
+*****
+
+How do I use matplotlib in a web application server?
+====================================================
+
+Many users report initial problems trying to use maptlotlib in web
+application servers, because by default matplotlib ships configured to
+work with a graphical user interface which may require an X11
+connection.  Since many barebones application servers do not have X11
+enabled, you may get errors if you don't configure matplotlib for use
+in these environments.  Most importantly, you need to decide what
+kinds of images you want to generate (PNG, PDF, SVG) and configure the
+appropriate default backend.  For 99% of users, this will be the Agg
+backend, which uses the C++ `antigrain <http://antigrain.com`_
+rendering engine to make nice PNGs.  The Agg backend is also
+configured to recognize requests to generate other output formats
+(PDF, PS, EPS, SVG).  The easiest way to configure matplotlib to use
+Agg is to call::
+
+    # do this before importing pylab or pyplot 
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+    
+Alternatively, you can avoid pylab/pyplot altogeher, which will give
+you a little more control, by calling the API directly as shown in
+`agg_oo.py <http://matplotlib.sf.net/examples/api/agg_oo.py`_ .
+
+You can either generate hardcopy on the filesystem by calling savefig::
+
+    # do this before importing pylab or pyplot 
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+    fig = plt.figure()
+    ax = fig.add_subplot(111)
+    ax.plot([1,2,3])
+    fig.savefig('test.png')
+
+or by saving to a file handle::
+
+    import sys
+    fig.savefig(sys.stdout)
+
+
+How do I use matplotlib with apache?
+------------------------------------
+
+TODO
+
+How do I use matplotlib with dhango?
+------------------------------------
+
+TODO
+
+How do I use matplotlib with zope?
+----------------------------------
+
+TODO
diff --git a/doc/faq/index.rst b/doc/faq/index.rst
@@ -13,5 +13,5 @@ Frequently asked questions about matplotlib
 
    installing_faq.rst
    troubleshooting_faq.rst
-   plotting_faq.rst
+   howto_faq.rst
 
diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -21,3 +21,9 @@ install directory.  To cleanly rebuild:
     * delete ``site-packages/matplotlib`` directory in the Python
       installation.  The location of ``site-packages`` is
       platform-specific.
+    * you may also want to clear some of the cache data that
+      matplotlib stores in your ``.matplotlib`` directory.  You can
+      find the location of this directory by doing::
+
+          import matplotlib
+          print matplotlib.get_configdir()
diff --git a/doc/faq/plotting_faq.rst b/doc/faq/plotting_faq.rst
diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst
@@ -12,15 +12,20 @@ lists first: There's a good chance someone else has already run into
 your problem.
 
 If not, please provide the following information in your e-mail to the
-mailing list:
+`mailing list
+<http://lists.sourceforge.net/mailman/listinfo/matplotlib-users>`_:
 
-  * your operating system
-  * matplotlib version
+  * your operating system; on Linux/UNIX post the output of ``uname -a``
+  * matplotlib version  : ``import matplotlib; print matplotlib.__version__``
   * where you obtained matplotlib (e.g. your Linux distribution's
     packages or the matplotlib Sourceforge site)
   * any customizations to your ``matplotlibrc`` file
-  * if the problem is reproducible, please try to provide a minimal,
+  * if the problem is reproducible, please try to provide a *minimal*,
     standalone Python script that demonstrates the problem
+  * you can get very helpful debugging output from matlotlib by
+    running your script with a ``verbose-helpful`` or
+    ``--verbose-debug`` flags and posting the verbose output the
+    lists.
 
 If you compiled matplotlib yourself, please also provide 
 
@@ -34,6 +39,8 @@ If you compiled matplotlib yourself, please also provide
     platform that are useful for the matplotlib developers to diagnose
     your problem.  
 
+  * your compiler version -- eg, ``gcc --version``
+
 Including this information in your first e-mail to the mailing list
 will save a lot of time.
 
