Add some hyperlinks. Clean up formatting.

mdboom · mdboom · commit 3d8eb612b2fb · 2008-05-23T17:41:58.000Z
svn path=/trunk/matplotlib/; revision=5231
diff --git a/doc/users_guide/introduction.txt b/doc/users_guide/introduction.txt
@@ -2,17 +2,18 @@
 Introduction
 ************
 
-matplotlib is a library for making 2D plots of arrays in python.
-Although it has its origins in emulating the MATLAB™ 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 and other extension
+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 it; it
+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
@@ -22,67 +23,71 @@ 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
+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 more than exceeds all of my needs).
+(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
+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)
+  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.
+  it
 
-* Making plots should be easy.
+* 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
+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
+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 hardcopy, SVG creates scalar vector graphics 
-hardcopy, Agg creates PNG output using the high quality antigrain 
-library that ships with matplotlib --- http://antigrain.com, GTK 
-embeds matplotlib in a GTK application, GTKAgg uses the antigrain 
-renderer to create a figure and embed it a GTK application, and so on 
-for WX, Tkinter, FLTK...
+: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
+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 OS X.
+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.
 
 Because there are so many ways people want to use a plotting library,
 there is a certain amount of complexity inherent in configuring the
-library so that it will work naturally the way you want it to.  Before 
-diving into these details, let's first explore matplotlib's simplicity 
+library so that it will work naturally the way you want it to.  Before
+diving into these details, let's first explore matplotlib's simplicity
 by comparing a typical matplotlib script with its analog in MATLAB™.
 
---- JDH
+--- JDH
