moved intro into separate doc

jdh2358 · jdh2358 · commit 65f366f44465 · 2008-06-02T21:21:29.000Z
svn path=/trunk/matplotlib/; revision=5368
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -172,7 +172,7 @@ emacs to strip trailing white space upon saving for python, C and C++:
             (lambda ()
 	    (add-hook 'write-file-functions 'delete-trailing-whitespace)))
 
-for older versions of emacs (emacs<22) you need to do:
+for older versions of emacs (emacs<22) you need to do: 
 
 .. code-block:: cl
 
diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -19,7 +19,7 @@ Unfortunately::
 does not properly clean the build directory, and does nothing to the
 install directory.  To cleanly rebuild:
 
-    * delete the ``build`` directory in the source tree 
+    * delete the ``build`` directory in the source tree
     * delete ``site-packages/matplotlib`` directory in the Python
       installation.  The location of ``site-packages`` is
       platform-specific.  You can find out where matplotlib is installed by doing::
@@ -63,7 +63,7 @@ There are a two primary ways to configure your backend.  One is to set
 the ``backend`` parameter in you ``matplotlibrc`` file (see
 :ref:`customizing-matplotlib`)::
 
-    backend : WXAgg   # use wxpython with antigrain (agg) rendering  
+    backend : WXAgg   # use wxpython with antigrain (agg) rendering
 
 The other is to use the matplotlib :func:`~matplotlib.use` directive::
 
@@ -74,7 +74,7 @@ If you use the ``use`` directive, this must be done before importing
 :mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
 
 If you are unsure what to do, and just want to get cranking, just set
-your backend to `TkAgg`.  This will do the right thing for 95% of the
+your backend to ``TkAgg``.  This will do the right thing for 95% of the
 users.  It gives you the option of running your scripts in batch or
 working interactively from the python shell, with the least amount of
 hassles, and is smart enough to do the right thing when you ask for
@@ -100,7 +100,8 @@ from this point to this point" and hence are scale free, and raster
 backends generate a pixel represenation of the line whose accuracy
 depends on a DPI setting.
 
-Here is a summary of the matplotlib rendering backends:
+Here is a summary of the matplotlib renders (there is an eponymous
+backed for each):
 
 ===============================   =====================================================================================
 Renderer (Filetypes)              Description
@@ -116,7 +117,7 @@ GDK (png, jpg, tiff..)            raster - the GDK drawing API for GTK
 And here are the user interfaces and renderer combinations supported:
 
 ============   ===================================================================================================
-Backend        Description  
+Backend        Description
 ============   ===================================================================================================
 GTKAgg         Agg rendering to a GTK canvas (`pygtk <http://www.pygtk.org>`_)
 GTK            GDK rendering to a GTK canvas (not recommended) (`pygtk <http://www.pygtk.org>`_)
@@ -129,3 +130,30 @@ Qt4Agg         Agg rendering to a Qt4 canvas (`pyqt <http://www.riverbankcomputi
 FLTKAgg        Agg rendering to a FLTK canvas (`pyfltk <http://pyfltk.sourceforge.net>`)_
 ============   ===================================================================================================
 
+
+OS X Questions
+==============
+
+.. _easy-install-osx-egg:
+
+How can I easy_install my egg?
+------------------------------
+
+I downloaded the egg for 0.98 from the matplotlib webpages,
+and I am trying to ``easy_install`` it, but I am getting an error::
+
+    > easy_install ./matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
+    Processing matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg
+    removing '/Library/Python/2.5/site-packages/matplotlib-0.98.0-py2.5-
+    ...snip...
+    Reading http://matplotlib.sourceforge.net
+    Reading http://cheeseshop.python.org/pypi/matplotlib/0.91.3
+    No local packages or download links found for matplotlib==0.98.0
+    error: Could not find suitable distribution for
+    Requirement.parse('matplotlib==0.98.0')
+
+If you rename ``matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg`` to
+``matplotlib-0.98.0-py2.5.egg``, ``easy_install`` will install it from
+the disk.  Many Mac OS X eggs with cruft at the end of the filename,
+which prevents their installation through easy_install.  Renaming is
+all it takes to install them; still, it's annoying.
diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst
@@ -63,3 +63,4 @@ tracker only periodically.  If your problem has been determined to be
 a bug and can not be quickly solved, you may be asked to file a bug in
 the tracker so the issue doesn't get lost.
 
+
diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -9,6 +9,7 @@
 
 .. toctree::
 
+    intro.rst
     pyplot_tutorial.rst
     mathtext.rst
     navigation_toolbar.rst
@@ -17,86 +18,3 @@
     event_handling.rst
 
 
-matplotlib is a library for making 2D plots of arrays in `Python
-<http://www.python.org>`_.  Although it has its origins in emulating
-the `MATLAB™ <http://www.mathworks.com>`_ graphics commands, it does
-not require MATLAB, and can be used in a Pythonic, object oriented
-way.  Although matplotlib is written primarily in pure Python, it
-makes heavy use of `NumPy <http://www.numpy.org>`_ and other extension
-code to provide good performance even for large arrays.
-
-matplotlib is designed with the philosophy that you should be able to
-create simple plots with just a few commands, or just one!  If you
-want to see a histogram of your data, you shouldn't need to
-instantiate objects, call methods, set properties, and so on; it
-should just work.
-
-For years, I used to use MATLAB exclusively for data analysis and
-visualization.  MATLAB excels at making nice looking plots easy.  When
-I began working with EEG data, I found that I needed to write
-applications to interact with my data, and developed and EEG analysis
-application in MATLAB.  As the application grew in complexity,
-interacting with databases, http servers, manipulating complex data
-structures, I began to strain against the limitations of MATLAB as a
-programming language, and decided to start over in Python.  Python
-more than makes up for all of MATLAB's deficiencies as a programming
-language, but I was having difficulty finding a 2D plotting package
-(for 3D `VTK <http://www.vtk.org/>`_) more than exceeds all of my needs).
-
-When I went searching for a Python plotting package, I had several
-requirements:
-
-* Plots should look great - publication quality.  One important
-  requirement for me is that the text looks good (antialiased, etc.)
-
-* Postscript output for inclusion with TeX documents
-
-* Embeddable in a graphical user interface for application
-  development
-
-* Code should be easy enough that I can understand it and extend
-  it
-
-* Making plots should be easy
-
-Finding no package that suited me just right, I did what any
-self-respecting Python programmer would do: rolled up my sleeves and
-dived in.  Not having any real experience with computer graphics, I
-decided to emulate MATLAB's plotting capabilities because that is
-something MATLAB does very well.  This had the added advantage that
-many people have a lot of MATLAB experience, and thus they can
-quickly get up to steam plotting in python.  From a developer's
-perspective, having a fixed user interface (the pylab interface) has
-been very useful, because the guts of the code base can be redesigned
-without affecting user code.
-
-The matplotlib code is conceptually divided into three parts: the
-*pylab interface* is the set of functions provided by
-:mod:`matplotlib.pylab` which allow the user to create plots with code
-quite similar to MATLAB figure generating code.  The *matplotlib
-frontend* or *matplotlib API* is the set of classes that do the heavy
-lifting, creating and managing figures, text, lines, plots and so on.
-This is an abstract interface that knows nothing about output.  The
-*backends* are device dependent drawing devices, aka renderers, that
-transform the frontend representation to hardcopy or a display device.
-Example backends: PS creates `PostScript®
-<http://http://www.adobe.com/products/postscript/>`_ hardcopy, SVG
-creates `Scalable Vector Graphics <http://www.w3.org/Graphics/SVG/>`_
-hardcopy, Agg creates PNG output using the high quality `Anti-Grain
-Geometry <http://www.antigrain.com>`_ library that ships with
-matplotlib, GTK embeds matplotlib in a `Gtk+ <http://www.gtk.org/>`_
-application, GTKAgg uses the Anti-Grain renderer to create a figure
-and embed it a Gtk+ application, and so on for `PDF
-<http://www.adobe.com/products/acrobat/adobepdf.html>`_, `WxWidgets
-<http://www.wxpython.org/>`_, `Tkinter
-<http://docs.python.org/lib/module-Tkinter.html>`_ etc.
-
-matplotlib is used by many people in many different contexts.  Some
-people want to automatically generate PostScript® files to send
-to a printer or publishers.  Others deploy matplotlib on a web
-application server to generate PNG output for inclusion in
-dynamically-generated web pages.  Some use matplotlib interactively
-from the Python shell in Tkinter on Windows™. My primary use is to
-embed matplotlib in a Gtk+ EEG application that runs on Windows, Linux
-and Macintosh OS X.
-
diff --git a/doc/users/intro.rst b/doc/users/intro.rst
@@ -0,0 +1,86 @@
+Introduction
+============
+
+matplotlib is a library for making 2D plots of arrays in `Python
+<http://www.python.org>`_.  Although it has its origins in emulating
+the `MATLAB™ <http://www.mathworks.com>`_ graphics commands, it does
+not require MATLAB, and can be used in a Pythonic, object oriented
+way.  Although matplotlib is written primarily in pure Python, it
+makes heavy use of `NumPy <http://www.numpy.org>`_ and other extension
+code to provide good performance even for large arrays.
+
+matplotlib is designed with the philosophy that you should be able to
+create simple plots with just a few commands, or just one!  If you
+want to see a histogram of your data, you shouldn't need to
+instantiate objects, call methods, set properties, and so on; it
+should just work.
+
+For years, I used to use MATLAB exclusively for data analysis and
+visualization.  MATLAB excels at making nice looking plots easy.  When
+I began working with EEG data, I found that I needed to write
+applications to interact with my data, and developed and EEG analysis
+application in MATLAB.  As the application grew in complexity,
+interacting with databases, http servers, manipulating complex data
+structures, I began to strain against the limitations of MATLAB as a
+programming language, and decided to start over in Python.  Python
+more than makes up for all of MATLAB's deficiencies as a programming
+language, but I was having difficulty finding a 2D plotting package
+(for 3D `VTK <http://www.vtk.org/>`_) more than exceeds all of my needs).
+
+When I went searching for a Python plotting package, I had several
+requirements:
+
+* Plots should look great - publication quality.  One important
+  requirement for me is that the text looks good (antialiased, etc.)
+
+* Postscript output for inclusion with TeX documents
+
+* Embeddable in a graphical user interface for application
+  development
+
+* Code should be easy enough that I can understand it and extend
+  it
+
+* Making plots should be easy
+
+Finding no package that suited me just right, I did what any
+self-respecting Python programmer would do: rolled up my sleeves and
+dived in.  Not having any real experience with computer graphics, I
+decided to emulate MATLAB's plotting capabilities because that is
+something MATLAB does very well.  This had the added advantage that
+many people have a lot of MATLAB experience, and thus they can
+quickly get up to steam plotting in python.  From a developer's
+perspective, having a fixed user interface (the pylab interface) has
+been very useful, because the guts of the code base can be redesigned
+without affecting user code.
+
+The matplotlib code is conceptually divided into three parts: the
+*pylab interface* is the set of functions provided by
+:mod:`matplotlib.pylab` which allow the user to create plots with code
+quite similar to MATLAB figure generating code.  The *matplotlib
+frontend* or *matplotlib API* is the set of classes that do the heavy
+lifting, creating and managing figures, text, lines, plots and so on.
+This is an abstract interface that knows nothing about output.  The
+*backends* are device dependent drawing devices, aka renderers, that
+transform the frontend representation to hardcopy or a display device.
+Example backends: PS creates `PostScript®
+<http://http://www.adobe.com/products/postscript/>`_ hardcopy, SVG
+creates `Scalable Vector Graphics <http://www.w3.org/Graphics/SVG/>`_
+hardcopy, Agg creates PNG output using the high quality `Anti-Grain
+Geometry <http://www.antigrain.com>`_ library that ships with
+matplotlib, GTK embeds matplotlib in a `Gtk+ <http://www.gtk.org/>`_
+application, GTKAgg uses the Anti-Grain renderer to create a figure
+and embed it a Gtk+ application, and so on for `PDF
+<http://www.adobe.com/products/acrobat/adobepdf.html>`_, `WxWidgets
+<http://www.wxpython.org/>`_, `Tkinter
+<http://docs.python.org/lib/module-Tkinter.html>`_ etc.
+
+matplotlib is used by many people in many different contexts.  Some
+people want to automatically generate PostScript® files to send
+to a printer or publishers.  Others deploy matplotlib on a web
+application server to generate PNG output for inclusion in
+dynamically-generated web pages.  Some use matplotlib interactively
+from the Python shell in Tkinter on Windows™. My primary use is to
+embed matplotlib in a Gtk+ EEG application that runs on Windows, Linux
+and Macintosh OS X.
+

Original file line number	Diff line number	Diff line change
`@@ -63,3 +63,4 @@ tracker only periodically. If your problem has been determined to be`
`63`	`63`	`a bug and can not be quickly solved, you may be asked to file a bug in`
`64`	`64`	`the tracker so the issue doesn't get lost.`
`65`	`65`
	`66`	`+`