second set of checkins from doc editor

8 files changed, 159 insertions, 106 deletions

diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
index 6d5e7bde0..51d97e53a 100644
--- a/doc/source/reference/arrays.classes.rst
+++ b/doc/source/reference/arrays.classes.rst
@@ -230,8 +230,8 @@ Character arrays (:mod:`numpy.char`)
 .. note::
    The chararray module exists for backwards compatibility with
    Numarray, it is not recommended for new development. If one needs
-   arrays of strings, use arrays of `dtype` `object_`, `string_` or
-   `unicode_`.
+   arrays of strings, use arrays of `dtype` `object_`, `str` or
+   `unicode`.
 
 These are enhanced arrays of either :class:`string_` type or
 :class:`unicode_` type.  These arrays inherit from the
@@ -242,7 +242,7 @@ character type. In addition, the :class:`chararray` has all of the
 standard :class:`string <str>` (and :class:`unicode`) methods,
 executing them on an element-by-element basis. Perhaps the easiest way
 to create a chararray is to use :meth:`self.view(chararray)
-<ndarray.view>` where *self* is an ndarray of string or unicode
+<ndarray.view>` where *self* is an ndarray of str or unicode
 data-type. However, a chararray can also be created using the
 :meth:`numpy.chararray` constructor, or via the
 :func:`numpy.char.array <core.defchararray.array>` function:
@@ -253,7 +253,7 @@ data-type. However, a chararray can also be created using the
    chararray
    core.defchararray.array
 
-Another difference with the standard ndarray of string data-type is
+Another difference with the standard ndarray of str data-type is
 that the chararray inherits the feature introduced by Numarray that
 white-space at the end of any element in the array will be ignored on
 item retrieval and comparison operations.
diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst
index 1bf7d1ac8..0cad2ac6e 100644
--- a/doc/source/reference/arrays.ndarray.rst
+++ b/doc/source/reference/arrays.ndarray.rst
@@ -120,6 +120,8 @@ strided scheme, and correspond to the strides:
 
 .. index:: single-segment, contiguous, non-contiguous
 
+where :math:`d_j` = `self.itemsize * self.shape[j]`.
+
 Both the C and Fortran orders are :term:`contiguous`, *i.e.,*
 :term:`single-segment`, memory layouts, in which every part of the
 memory block can be accessed by some combination of the indices.
@@ -231,7 +233,7 @@ Array methods
 
 An :class:`ndarray` object has many methods which operate on or with
 the array in some fashion, typically returning an array result. These
-methods are briefly explained below. (Each method's doc string has a
+methods are briefly explained below. (Each method's docstring has a
 more complete description.)
 
 For the following methods there are also corresponding functions in
@@ -317,11 +319,45 @@ Many of these methods take an argument named *axis*. In such cases,
 - If *axis* is *None* (the default), the array is treated as a 1-D
   array and the operation is performed over the entire array. This
   behavior is also the default if self is a 0-dimensional array or
-  array scalar.
+  array scalar. (An array scalar is an instance of the types/classes
+  float32, float64, etc., whereas a 0-dimensional array is an ndarray
+  instance containing precisely one array scalar.)
 
 - If *axis* is an integer, then the operation is done over the given axis
   (for each 1-D subarray that can be created along the given axis).
 
+.. admonition:: Example of the *axis* argument
+
+   A 3-dimensional array of size 3 x 3 x 3, summed over each of its
+   three axes
+
+   >>> x
+   array([[[ 0,  1,  2],
+           [ 3,  4,  5],
+           [ 6,  7,  8]],
+          [[ 9, 10, 11],
+           [12, 13, 14],
+           [15, 16, 17]],
+          [[18, 19, 20],
+           [21, 22, 23],
+           [24, 25, 26]]])
+   >>> x.sum(axis=0)
+   array([[27, 30, 33],
+          [36, 39, 42],
+          [45, 48, 51]])
+   >>> # for sum, axis is the first keyword, so we may omit it,
+   >>> # specifying only its value
+   >>> x.sum(0), x.sum(1), x.sum(2)
+   (array([[27, 30, 33],
+           [36, 39, 42],
+           [45, 48, 51]]),
+    array([[ 9, 12, 15],
+           [36, 39, 42],
+           [63, 66, 69]]),
+    array([[ 3, 12, 21],
+           [30, 39, 48],
+           [57, 66, 75]]))
+
 The parameter *dtype* specifies the data type over which a reduction
 operation (like summing) should take place. The default reduce data
 type is the same as the data type of *self*. To avoid overflow, it can
@@ -333,7 +369,6 @@ argument must be an :class:`ndarray` and have the same number of
 elements. It can have a different data type in which case casting will
 be performed.
 
-
 .. autosummary::
    :toctree: generated/
 
diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 3716fa16b..49d073b7e 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -2372,7 +2372,7 @@ Other conversions
     signed and unsigned integers, floating point numbers, and
     complex-floating point numbers are recognized and converted. Other
     values of gentype are returned. This function can be used to
-    convert, for example, the string'f4' to :cdata:`NPY_FLOAT32`.
+    convert, for example, the string 'f4' to :cdata:`NPY_FLOAT32`.
 
 
 Miscellaneous
diff --git a/doc/source/reference/distutils.rst b/doc/source/reference/distutils.rst
index bb01a529a..63174c2c7 100644
--- a/doc/source/reference/distutils.rst
+++ b/doc/source/reference/distutils.rst
@@ -6,7 +6,7 @@ Packaging (:mod:`numpy.distutils`)
 
 NumPy provides enhanced distutils functionality to make it easier to
 build and install sub-packages, auto-generate code, and extension
-modules that use Fortran-compiled libraries. To use features of numpy
+modules that use Fortran-compiled libraries. To use features of NumPy
 distutils, use the :func:`setup <core.setup>` command from
 :mod:`numpy.distutils.core`. A useful :class:`Configuration
 <misc_util.Configuration>` class is also provided in
@@ -33,7 +33,6 @@ misc_util
 
    Configuration
    get_numpy_include_dirs
-   get_numarray_include_dirs
    dict_append
    appendpath
    allpath
@@ -128,13 +127,13 @@ Other modules
 Building Installable C libraries
 ================================
 
-Conventional C libraries (installed through add_library) are not installed, and
+Conventional C libraries (installed through `add_library`) are not installed, and
 are just used during the build (they are statically linked).  An installable C
 library is a pure C library, which does not depend on the python C runtime, and
-is installed such as it may be used by third-party packages. To build and
-install the C library, you just use the method add_installed_library instead of
-add_library, which takes the same arguments except for an additional
-install_dir argument::
+is installed such that it may be used by third-party packages. To build and
+install the C library, you just use the method `add_installed_library` instead of
+`add_library`, which takes the same arguments except for an additional
+``install_dir`` argument::
 
   >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
 
@@ -142,8 +141,8 @@ npy-pkg-config files
 --------------------
 
 To make the necessary build options available to third parties, you could use
-the npy-pkg-config mechanism implemented in numpy.distutils. This mechanism is
-based on an .ini file which contains all the options. A .ini file is very
+the `npy-pkg-config` mechanism implemented in `numpy.distutils`. This mechanism is
+based on a .ini file which contains all the options. A .ini file is very
 similar to .pc files as used by the pkg-config unix utility::
 
   [meta]
@@ -162,7 +161,7 @@ similar to .pc files as used by the pkg-config unix utility::
 
 Generally, the file needs to be generated during the build, since it needs some
 information known at build time only (e.g. prefix). This is mostly automatic if
-one uses the Configuration method add_npy_pkg_config. Assuming we have a
+one uses the `Configuration` method `add_npy_pkg_config`. Assuming we have a
 template file foo.ini.in as follows::
 
   [meta]
@@ -186,22 +185,23 @@ and the following code in setup.py::
   >>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst)
 
 This will install the file foo.ini into the directory package_dir/lib, and the
-foo.ini file will be generated from foo.ini.in, where each @version@ will be
-replaced by subst_dict['version']. The dictionary has an additional prefix
+foo.ini file will be generated from foo.ini.in, where each ``@version@`` will be
+replaced by ``subst_dict['version']``. The dictionary has an additional prefix
 substitution rule automatically added, which contains the install prefix (since
 this is not easy to get from setup.py).  npy-pkg-config files can also be
 installed at the same location as used for numpy, using the path returned from
-get_npy_pkg_dir function.
+`get_npy_pkg_dir` function.
 
 Reusing a C library from another package
 ----------------------------------------
 
-Info are easily retrieved from the get_info function in numpy.distutils.misc_util::
+Info are easily retrieved from the `get_info` function in
+`numpy.distutils.misc_util`::
 
   >>> info = get_info('npymath')
   >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)
 
-An additional list of paths to look for .ini files can be given to get_info.
+An additional list of paths to look for .ini files can be given to `get_info`.
 
 Conversion of ``.src`` files
 ============================
diff --git a/doc/source/reference/routines.math.rst b/doc/source/reference/routines.math.rst
index 326391292..7ce77c24d 100644
--- a/doc/source/reference/routines.math.rst
+++ b/doc/source/reference/routines.math.rst
@@ -19,6 +19,8 @@ Trigonometric functions
    degrees
    radians
    unwrap
+   deg2rad
+   rad2deg
 
 Hyperbolic functions
 --------------------
@@ -43,6 +45,7 @@ Rounding
    fix
    floor
    ceil
+   trunc
 
 Sums, products, differences
 ---------------------------
@@ -67,10 +70,13 @@ Exponents and logarithms
 
    exp
    expm1
+   exp2
    log
    log10
    log2
    log1p
+   logaddexp
+   logaddexp2
 
 Other special functions
 -----------------------
@@ -86,6 +92,7 @@ Floating point routines
    :toctree: generated/
 
    signbit
+   copysign
    frexp
    ldexp
 
diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index 59cdb71de..77269be58 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -313,7 +313,7 @@ possess. None of the attributes can be set.
 ============  =================================================================
 **__doc__**   A docstring for each ufunc. The first part of the docstring is
               dynamically generated from the number of outputs, the name, and
-              the number of inputs. The second part of the doc string is
+              the number of inputs. The second part of the docstring is
               provided at creation time and stored with the ufunc.
 
 **__name__**  The name of the ufunc.
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index ed8e186a7..c365c0af3 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -1,20 +1,23 @@
 .. _user:
 
 ################
-Numpy User Guide
+NumPy User Guide
 ################
 
-This guide explains how to make use of different features
-of Numpy. For a detailed documentation about different functions
-and classes, see :ref:`reference`.
+This guide is intended as an introductory overview of NumPy and
+explains how to install and make use of the most important features of
+NumPy. For detailed reference documentation of the functions and
+classes contained in the package, see the :ref:`reference`.
 
 .. warning::
 
-   This "User Guide" is still very much work in progress; the material
-   is not organized, and many aspects of Numpy are not covered.
+   This "User Guide" is still a work in progress; some of the material
+   is not organized, and several aspects of NumPy are not yet covered
+   in sufficient detail. However, we are continually working to
+   improve the documentation.
 
-   More documentation for Numpy can be found on the
-   `scipy.org <http://www.scipy.org/Documentation>`__ website.
+   More documentation for NumPy can be found on the `numpy.org
+   <http://www.numpy.org>`__ website.
 
 .. toctree::
    :maxdepth: 2
diff --git a/doc/source/user/whatisnumpy.rst b/doc/source/user/whatisnumpy.rst
index 3a9abb79d..1c3f96b8b 100644
--- a/doc/source/user/whatisnumpy.rst
+++ b/doc/source/user/whatisnumpy.rst
@@ -2,52 +2,59 @@
 What is NumPy?
 **************
 
-NumPy is the fundamental package for scientific computing in Python.  It is a
-Python library that provides a multidimensional array object, various derived
-objects (such as masked arrays and matrices), and an assortment of routines
-for fast operations on arrays, including mathematical, logical, shape
-manipulation, sorting, I/O, discrete Fourier transform, basic linear algebra,
-basic statistical and random simulation, etc., etc., etc.
-
-The core of the NumPy package, however, is the `ndarray` object.  This
-encapsulates *n*-dimensional arrays of homogeneous data.  There are several
-important differences between NumPy arrays and the standard Python sequences:
-
-- Unlike Python lists, NumPy arrays have a fixed size - changing their size
-  *will* create a new array and delete the original.
-
-- Unlike Python tuples, the elements in a NumPy array are all required to be
-  the same data type, and thus *will* be the same size in memory.  The
-  exception: one can have arrays of (Python, including NumPy) objects, thereby
+NumPy is the fundamental package for scientific computing in Python.
+It is a Python library that provides a multidimensional array object,
+various derived objects (such as masked arrays and matrices), and an
+assortment of routines for fast operations on arrays, including
+mathematical, logical, shape manipulation, sorting, selecting, I/O,
+discrete Fourier transforms, basic linear algebra, basic statistical
+operations, random simulation and much more.
+
+At the core of the NumPy package, is the `ndarray` object.  This
+encapsulates *n*-dimensional arrays of homogeneous data types, with
+many operations being performed in compiled code for performance.
+There are several important differences between NumPy arrays and the
+standard Python sequences:
+
+- NumPy arrays have a fixed size at creation, unlike Python lists
+  (which can grow dynamically). Changing the size of an `ndarray` will
+  create a new array and delete the original.
+
+- The elements in a NumPy array are all required to be of the same
+  data type, and thus will be the same size in memory.  The exception:
+  one can have arrays of (Python, including NumPy) objects, thereby
   allowing for arrays of different sized elements.
 
-- NumPy arrays facilitate advanced mathematical and other types of operations
-  on large amounts of data.  Typically, such operations are executed much
-  faster and with less code compared to what is possible using Python's
-  built-in sequences.
+- NumPy arrays facilitate advanced mathematical and other types of
+  operations on large numbers of data.  Typically, such operations are
+  executed more efficiently and with less code than is possible using
+  Python's built-in sequences.
 
-- A growing plethora of scientific and mathematical Python-based packages are
-  keyed to using NumPy arrays; though these typically support Python-sequence
-  input, they convert such input to NumPy arrays prior to processing, and they
-  output NumPy arrays.  In other words, in order to *efficiently* use much
-  (perhaps even most) of today's scientific/mathematical Python-based software, just
-  knowing how to use Python's built-in sequence types is insufficient - one
-  also needs to know how to use NumPy arrays.
+- A growing plethora of scientific and mathematical Python-based
+  packages are using NumPy arrays; though these typically support
+  Python-sequence input, they convert such input to NumPy arrays prior
+  to processing, and they often output NumPy arrays.  In other words,
+  in order to efficiently use much (perhaps even most) of today's
+  scientific/mathematical Python-based software, just knowing how to
+  use Python's built-in sequence types is insufficient - one also
+  needs to know how to use NumPy arrays.
 
 The points about sequence size and speed are particularly important in
-scientific computing.  For a simple example, consider the case of multiplying
-every element in a 1-D sequence with the corresponding element in another
-sequence of the same length.  If the data are in two Python lists, ``a`` and
-``b``, we could iterate over each element::
+scientific computing.  As a simple example, consider the case of
+multiplying each element in a 1-D sequence with the corresponding
+element in another sequence of the same length.  If the data are
+stored in two Python lists, ``a`` and ``b``, we could iterate over
+each element::
 
   c = []
   for i in range(len(a)):
       c.append(a[i]*b[i])
 
-This gives the right answer, but if ``a`` and ``b`` each contain millions of
-numbers, we will be waiting a rather long time fot it.  We could accomplish
-the same task much more quickly in C by writing (neglecting variable
-declarations and initializations, memory allocation, etc.)
+This produces the correct answer, but if ``a`` and ``b`` each contain
+millions of numbers, we will pay the price for the inefficiencies of
+looping in Python.  We could accomplish the same task much more
+quickly in C by writing (for clarity we neglect variable declarations
+and initializations, memory allocation, etc.)
 
 ::
 
@@ -55,11 +62,11 @@ declarations and initializations, memory allocation, etc.)
     c[i] = a[i]*b[i];
   }
 
-This saves all the overhead involved in interpreting the Python code and
-manipulating Python objects, but at the expense of our beloved Python benefits.
-Furthermore, the coding work required increases with the dimensionality of our
-data. In the case of a 2-D array, for example, the C code (abridged as before)
-expands to
+This saves all the overhead involved in interpreting the Python code
+and manipulating Python objects, but at the expense of the benefits
+gained from coding in Python.  Furthermore, the coding work required
+increases with the dimensionality of our data. In the case of a 2-D
+array, for example, the C code (abridged as before) expands to
 
 ::
 
@@ -69,9 +76,10 @@ expands to
     }
   }
 
-NumPy gives us the best of both worlds: such element-by-element operation is
-the "default mode" when an `ndarray` is involved, but the element-by-element
-operation is speedily executed by pre-compiled C code.  In NumPy
+NumPy gives us the best of both worlds: element-by-element operations
+are the "default mode" when an `ndarray` is involved, but the
+element-by-element operation is speedily executed by pre-compiled C
+code.  In NumPy
 
 ::
 
@@ -79,42 +87,42 @@ operation is speedily executed by pre-compiled C code.  In NumPy
 
 does what the earlier examples do, at near-C speeds, but with the code
 simplicity we expect from something based on Python (indeed, the NumPy
-idiom is even simpler!)  This last example illustrates two of NumPy's
+idiom is even simpler!).  This last example illustrates two of NumPy's
 features which are the basis of much of its power: vectorization and
 broadcasting.
 
-Vectorization describes the absence of any *explicit* looping, indexing, etc.,
-in the code - these things are taking place, of course, just "behind the
-scenes" (in optimized, pre-compiled C code).  Vectorized code has many
-advantages, among which are:
+Vectorization describes the absence of any explicit looping, indexing,
+etc., in the code - these things are taking place, of course, just
+"behind the scenes" (in optimized, pre-compiled C code).  Vectorized
+code has many advantages, among which are:
 
 - vectorized code is more concise and easier to read
 
 - fewer lines of code generally means fewer bugs
 
-- the code more closely resembles standard mathematical notation (making it
-  easier, typically, to correctly code written mathematics)
-
-- vectorization results in more "Pythonic" code (without vectorization, our
-  code would still be littered with ``for`` loops; though of course not absent
-  in Python, generally speaking, we feel that if we have to use a ``for`` loop
-  in Python, we must be doing something wrong!) :-)
-
-Broadcasting, on the other hand, is the term used to describe the *implicit*
-element-by-element behavior of operations; generally speaking, in NumPy all
-"operations" (i.e., not just arithmetic operations, but logical, bit-wise,
-function, etc.) behave in this implicit element-by-element fashion, i.e., they
-"broadcast."  Moreover, in the example above, ``a`` and ``b`` could be
-multidimensional arrays of the same shape, or a scalar and an array, or even
-two arrays of different shapes, as long as the smaller one is "expandable" to
+- the code more closely resembles standard mathematical notation
+  (making it easier, typically, to correctly code mathematical
+  constructs)
+
+- vectorization results in more "Pythonic" code (without
+  vectorization, our code would still be littered with inefficient and
+  difficult to read ``for`` loops.
+
+Broadcasting is the term used to describe the implicit
+element-by-element behavior of operations; generally speaking, in
+NumPy all operations (i.e., not just arithmetic operations, but
+logical, bit-wise, functional, etc.) behave in this implicit
+element-by-element fashion, i.e., they broadcast.  Moreover, in the
+example above, ``a`` and ``b`` could be multidimensional arrays of the
+same shape, or a scalar and an array, or even two arrays of with
+different shapes.  Provided that the smaller array is "expandable" to
 the shape of the larger in such a way that the resulting broadcast is
-unambiguous and "makes sense" (the detailed "rules" of broadcasting are
-described in `numpy.doc.broadcasting`).
-
-Finally, in tune with the rest of Python, NumPy fully supports an
-object-oriented approach, starting, once again, with `ndarray`.
-Unexceptionally, `ndarray` is a class, possessing many, *many* attributes,
-both method and "other."  Many, if not all, of its attributes duplicate
-(indeed, call) functions in the outer-most NumPy namespace, so the programmer
-has complete freedom to code in whichever paradigm she prefers and/or that
-seems most appropriate to the task at hand.
+unambiguous (for detailed "rules" of broadcasting see
+`numpy.doc.broadcasting`).
+
+NumPy fully supports an object-oriented approach, starting, once
+again, with `ndarray`.  For example, `ndarray` is a class, possessing
+numerous methods and attributes.  Many, of it's methods mirror
+functions in the outer-most NumPy namespace, giving the programmer has
+complete freedom to code in whichever paradigm she prefers and/or
+which seems most appropriate to the task at hand.