Merge pull request matplotlib#5204 from gcallah/master

Minor cleanup work on navigation, text, and customization files.

Author: mdboom

doc/users/navigation_toolbar.rst

@@ -15,16 +15,16 @@ the buttons at the bottom of the toolbar
 
 .. image:: ../../lib/matplotlib/mpl-data/images/forward.png
 
-The ``Forward`` and ``Back`` buttons
-    These are akin to the web browser forward and back buttons.  They
-    are used to navigate back and forth between previously defined
-    views.  They have no meaning unless you have already navigated
-    somewhere else using the pan and zoom buttons.  This is analogous
+The ``Home``, ``Forward`` and ``Back`` buttons
+    These are akin to a web browser's home, forward and back controls.
+    ``Forward`` and ``Back`` are used to navigate back and forth between
+    previously defined views.  They have no meaning unless you have already
+    navigated somewhere else using the pan and zoom buttons.  This is analogous
     to trying to click ``Back`` on your web browser before visiting a
-    new page --nothing happens.  ``Home`` always takes you to the
-    first, default view of your data.  For ``Home``, ``Forward`` and
-    ``Back``, think web browser where data views are web pages.  Use
-    the pan and zoom to rectangle to define new views.
+    new page or ``Forward`` before you have gone back to a page --
+    nothing happens.  ``Home`` always takes you to the
+    first, default view of your data. Again, all of these buttons should
+    feel very familiar to any user of a web browser.
 
 .. image:: ../../lib/matplotlib/mpl-data/images/move.png
 
@@ -37,11 +37,11 @@ The ``Pan/Zoom`` button
     where you released.  If you press 'x' or 'y' while panning the
     motion will be constrained to the x or y axis, respectively.  Press
     the right mouse button to zoom, dragging it to a new position.
-    The x axis will be zoomed in proportionate to the rightward
-    movement and zoomed out proportionate to the leftward movement.
-    Ditto for the y axis and up/down motions.  The point under your
+    The x axis will be zoomed in proportionately to the rightward
+    movement and zoomed out proportionately to the leftward movement.
+    The same is true for the y axis and up/down motions.  The point under your
     mouse when you begin the zoom remains stationary, allowing you to
-    zoom to an arbitrary point in the figure.  You can use the
+    zoom in or out around that point as much as you wish.  You can use the
     modifier keys 'x', 'y' or 'CONTROL' to constrain the zoom to the x
     axis, the y axis, or aspect ratio preserve, respectively.
 
@@ -54,7 +54,7 @@ The ``Pan/Zoom`` button
 
 The ``Zoom-to-rectangle`` button
     Click this toolbar button to activate this mode.  Put your mouse
-    somewhere over and axes and press the left mouse button.  Drag the
+    somewhere over an axes and press the left mouse button.  Drag the
     mouse while holding the button to a new location and release.  The
     axes view limits will be zoomed to the rectangle you have defined.
     There is also an experimental 'zoom out to rectangle' in this mode
@@ -64,9 +64,10 @@ The ``Zoom-to-rectangle`` button
 .. image:: ../../lib/matplotlib/mpl-data/images/subplots.png
 
 The ``Subplot-configuration`` button
-    Use this tool to configure the parameters of the subplot: the
-    left, right, top, bottom, space between the rows and space between
-    the columns.
+    Use this tool to configure the appearance of the subplot:
+    you can stretch or compress the left, right, top, or bottom
+    side of the subplot, or the space between the rows or 
+    space between the columns.
 
 .. image:: ../../lib/matplotlib/mpl-data/images/filesave.png
 

doc/users/style_sheets.rst

@@ -6,7 +6,8 @@ Customizing plots with style sheets
 
 
 The ``style`` package adds support for easy-to-switch plotting "styles" with
-the same parameters as a matplotlibrc_ file.
+the same parameters as a matplotlibrc_ file (which is read at startup to 
+configure matplotlib).
 
 There are a number of pre-defined styles provided by matplotlib. For
 example, there's a pre-defined style called "ggplot", which emulates the
@@ -28,8 +29,8 @@ You can create custom styles and use them by calling ``style.use`` with the
 path or URL to the style sheet. Alternatively, if you add your ``<style-name>.mplstyle`` 
 file to ``mpl_configdir/stylelib``, you can reuse your custom style sheet with a call to 
 ``style.use(<style-name>)``. By default ``mpl_configdir`` should be ``~/.config/matplotlib``, 
-but you can check where yours is with ``matplotlib.get_configdir()``, you may need to 
-create this directory. Note that a custom style sheet in ``mpl_configdir/stylelib`` 
+but you can check where yours is with ``matplotlib.get_configdir()``. (You may need to 
+create this directory.) Note that a custom style sheet in ``mpl_configdir/stylelib`` 
 will override a style sheet defined by matplotlib if the styles have the same name.
 
 For example, you might want to create

doc/users/text_intro.rst

@@ -3,22 +3,25 @@
 Text introduction
 =================
 
-matplotlib has excellent text support, including mathematical
-expressions, truetype support for raster and vector outputs, newline
-separated text with arbitrary rotations, and unicode support.  Because
-we embed the fonts directly in the output documents, e.g., for postscript
+matplotlib has extensive text support, including support for
+mathematical expressions, truetype support for raster and 
+vector outputs, newline separated text with arbitrary 
+rotations, and unicode support.  Because it embeds
+fonts directly in output documents, e.g., for postscript
 or PDF, what you see on the screen is what you get in the hardcopy.
 `FreeType <http://www.freetype.org/>`_ support
 produces very nice, antialiased fonts, that look good even at small
 raster sizes.  matplotlib includes its own
-:mod:`matplotlib.font_manager`, thanks to Paul Barrett, which
-implements a cross platform, W3C compliant font finding algorithm.
-
-You have total control over every text property (font size, font
-weight, text location and color, etc) with sensible defaults set in
-the rc file.  And significantly for those interested in mathematical
+:mod:`matplotlib.font_manager` (thanks to Paul Barrett), which
+implements a cross platform, `W3C <http://www.w3.org/>`
+compliant font finding algorithm.
+
+The user has a great deal of control over text properties (font size, font
+weight, text location and color, etc.) with sensible defaults set in
+the `rc file <http://matplotlib.org/users/customizing.html>`.
+And significantly, for those interested in mathematical
 or scientific figures, matplotlib implements a large number of TeX
-math symbols and commands, to support :ref:`mathematical expressions
+math symbols and commands, supporting :ref:`mathematical expressions
 <mathtext-tutorial>` anywhere in your figure.
 
 
@@ -31,10 +34,10 @@ interface
 * :func:`~matplotlib.pyplot.text` - add text at an arbitrary location to the ``Axes``;
   :meth:`matplotlib.axes.Axes.text` in the API.
 
-* :func:`~matplotlib.pyplot.xlabel` - add an axis label to the x-axis;
+* :func:`~matplotlib.pyplot.xlabel` - add a label to the x-axis;
   :meth:`matplotlib.axes.Axes.set_xlabel` in the API.
 
-* :func:`~matplotlib.pyplot.ylabel` - add an axis label to the y-axis;
+* :func:`~matplotlib.pyplot.ylabel` - add a label to the y-axis;
   :meth:`matplotlib.axes.Axes.set_ylabel` in the API.
 
 * :func:`~matplotlib.pyplot.title` - add a title to the ``Axes``;