Re-base the date-time branch back to the trunk.

17 files changed, 402 insertions, 272 deletions

diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
index 671c95bbf..f9abfbafa 100644
--- a/doc/source/reference/arrays.classes.rst
+++ b/doc/source/reference/arrays.classes.rst
@@ -47,14 +47,29 @@ customize:
    update meta-information from the "parent." Subclasses inherit a
    default implementation of this method that does nothing.
 
-.. function:: __array_wrap__(array)
-
-   This method should return an instance of the subclass from the
-   :class:`ndarray` object passed in. For example, this is called
-   after every :ref:`ufunc <ufuncs.output-type>` for the object with
-   the highest array priority. The ufunc-computed array object is
-   passed in and whatever is returned is passed to the
-   user. Subclasses inherit a default implementation of this method.
+.. function:: __array_prepare__(array, context=None)
+
+   At the beginning of every :ref:`ufunc <ufuncs.output-type>`, this
+   method is called on the input object with the highest array
+   priority, or the output object if one was specified. The output
+   array is passed in and whatever is returned is passed to the ufunc.
+   Subclasses inherit a default implementation of this method which
+   simply returns the output array unmodified. Subclasses may opt to
+   use this method to transform the output array into an instance of
+   the subclass and update metadata before returning the array to the
+   ufunc for computation.
+
+.. function:: __array_wrap__(array, context=None)
+
+   At the end of every :ref:`ufunc <ufuncs.output-type>`, this method
+   is called on the input object with the highest array priority, or
+   the output object if one was specified. The ufunc-computed array
+   is passed in and whatever is returned is passed to the user.
+   Subclasses inherit a default implementation of this method, which
+   transforms the array into a new instance of the object's class. Subclasses
+   may opt to use this method to transform the output array into an
+   instance of the subclass and update metadata before returning the
+   array to the user.
 
 .. data:: __array_priority__
 
diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst
index 0def05ced..1bf7d1ac8 100644
--- a/doc/source/reference/arrays.ndarray.rst
+++ b/doc/source/reference/arrays.ndarray.rst
@@ -9,14 +9,14 @@ The N-dimensional array (:class:`ndarray`)
 An :class:`ndarray` is a (usually fixed-size) multidimensional
 container of items of the same type and size. The number of dimensions
 and items in an array is defined by its :attr:`shape <ndarray.shape>`,
-which is a :class:`tuple` of *N* integers that specify the sizes of
+which is a :class:`tuple` of *N* positive integers that specify the sizes of
 each dimension. The type of items in the array is specified by a
 separate :ref:`data-type object (dtype) <arrays.dtypes>`, one of which
 is associated with each ndarray.
 
-As with other container objects in Python, the contents of a
+As with other container objects in Python, the contents of an
 :class:`ndarray` can be accessed and modified by :ref:`indexing or
-slicing <arrays.indexing>` the array (using for example *N* integers),
+slicing <arrays.indexing>` the array (using, for example, *N* integers),
 and via the methods and attributes of the :class:`ndarray`.
 
 .. index:: view, base
@@ -42,15 +42,19 @@ objects implementing the :class:`buffer` or :ref:`array
    >>> x.dtype
    dtype('int32')
 
-   The array can be indexed using a Python container-like syntax:
+   The array can be indexed using Python container-like syntax:
 
-   >>> x[1,2]
+   >>> x[1,2] # i.e., the element of x in the *second* row, *third* column
    6
 
    For example :ref:`slicing <arrays.indexing>` can produce views of the array:
 
    >>> y = x[:,1]
-   >>> y[0] = 9
+   >>> y
+   array([2, 5])
+   >>> y[0] = 9 # this also changes the corresponding element in x
+   >>> y
+   array([9, 5])
    >>> x
    array([[1, 9, 3],
           [4, 5, 6]])
@@ -95,7 +99,7 @@ the bytes are interpreted is defined by the :ref:`data-type object
 .. index:: C-order, Fortran-order, row-major, column-major, stride, offset
 
 A segment of memory is inherently 1-dimensional, and there are many
-different schemes of arranging the items of an *N*-dimensional array to
+different schemes for arranging the items of an *N*-dimensional array in
 a 1-dimensional block. Numpy is flexible, and :class:`ndarray` objects
 can accommodate any *strided indexing scheme*. In a strided scheme,
 the N-dimensional index :math:`(n_0, n_1, ..., n_{N-1})` corresponds
@@ -105,10 +109,10 @@ to the offset (in bytes)
 
 from the beginning of the memory block associated with the
 array. Here, :math:`s_k` are integers which specify the :obj:`strides
-<ndarray.strides>` of the array. The :term:`column-major` order (used
-for example in the Fortran language and in *Matlab*) and
-:term:`row-major` order (used in C) are special cases of the strided
-scheme, and correspond to the strides:
+<ndarray.strides>` of the array. The :term:`column-major` order (used,
+for example, in the Fortran language and in *Matlab*) and
+:term:`row-major` order (used in C) schemes are just specific kinds of
+strided scheme, and correspond to the strides:
 
 .. math::
 
@@ -116,12 +120,12 @@ scheme, and correspond to the strides:
 
 .. index:: single-segment, contiguous, non-contiguous
 
-Both the C and Fortran orders are :term:`contiguous`, *i.e.*
+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.
 
 Data in new :class:`ndarrays <ndarray>` is in the :term:`row-major`
-(C) order, unless otherwise specified, but for example :ref:`basic
+(C) order, unless otherwise specified, but, for example, :ref:`basic
 array slicing <arrays.indexing>` often produces :term:`views <view>`
 in a different scheme.
 
@@ -227,7 +231,8 @@ 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 explained below.
+methods are briefly explained below. (Each method's doc string has a
+more complete description.)
 
 For the following methods there are also corresponding functions in
 :mod:`numpy`: :func:`all`, :func:`any`, :func:`argmax`,
@@ -433,7 +438,7 @@ Arithmetic:
 .. note::
 
    - Any third argument to :func:`pow()` is silently ignored,
-     as the underlying :func:`ufunc <power>` only takes two arguments.
+     as the underlying :func:`ufunc <power>` takes only two arguments.
 
    - The three division operators are all defined; :obj:`div` is active
      by default, :obj:`truediv` is active when
@@ -472,7 +477,7 @@ Arithmetic, in-place:
    the array.  Therefore, for mixed precision calculations, ``A {op}=
    B`` can be different than ``A = A {op} B``. For example, suppose
    ``a = ones((3,3))``. Then, ``a += 3j`` is different than ``a = a +
-   3j``: While they both perform the same computation, ``a += 3``
+   3j``: while they both perform the same computation, ``a += 3``
    casts the result to fit back in ``a``, whereas ``a = a + 3j``
    re-binds the name ``a`` to the result.
 
diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst
index 33d5ceff6..75daf2a08 100644
--- a/doc/source/reference/arrays.scalars.rst
+++ b/doc/source/reference/arrays.scalars.rst
@@ -204,8 +204,6 @@ elements the data type consists of.)
    :mod:`struct` module.
 
 
-.. note:: XXX: what to put in the type docstrings, and where to put them?
-
 Attributes
 ==========
 
@@ -235,7 +233,6 @@ attribute. Otherwise, they share the same attributes as arrays:
    generic.__array_priority__
    generic.__array_wrap__
 
-.. note:: XXX: import the documentation into the docstrings?
 
 Indexing
 ========
@@ -273,7 +270,6 @@ The exceptions to the above rules are given below:
    generic.__setstate__
    generic.setflags
 
-.. note:: XXX: import the documentation into the docstrings?
 
 Defining new types
 ==================
diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst
index 654201d73..8ce362079 100644
--- a/doc/source/reference/c-api.array.rst
+++ b/doc/source/reference/c-api.array.rst
@@ -251,14 +251,16 @@ From other objects
 .. cfunction:: PyObject* PyArray_FromAny(PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context)
 
     This is the main function used to obtain an array from any nested
-    sequence, or object that exposes the array interface, ``op``. The
-    parameters allow specification of the required *type*, the
+    sequence, or object that exposes the array interface, *op*. The
+    parameters allow specification of the required *dtype*, the
     minimum (*min_depth*) and maximum (*max_depth*) number of
     dimensions acceptable, and other *requirements* for the array. The
     *dtype* argument needs to be a :ctype:`PyArray_Descr` structure
     indicating the desired data-type (including required
     byteorder). The *dtype* argument may be NULL, indicating that any
-    data-type (and byteorder) is acceptable. If you want to use
+    data-type (and byteorder) is acceptable. Unless ``FORCECAST`` is
+    present in ``flags``, this call will generate an error if the data
+    type cannot be safely obtained from the object. If you want to use
     ``NULL`` for the *dtype* and ensure the array is notswapped then
     use :cfunc:`PyArray_CheckFromAny`. A value of 0 for either of the
     depth parameters causes the parameter to be ignored. Any of the
@@ -270,7 +272,8 @@ From other objects
     filled from *op* using the sequence protocol). The new array will
     have :cdata:`NPY_DEFAULT` as its flags member. The *context* argument
     is passed to the :obj:`__array__` method of *op* and is only used if
-    the array is constructed that way.
+    the array is constructed that way. Almost always this
+    parameter is ``NULL``.
 
     .. cvar:: NPY_C_CONTIGUOUS
 
@@ -1001,6 +1004,24 @@ Special functions for PyArray_OBJECT
 Array flags
 -----------
 
+The ``flags`` attribute of the ``PyArrayObject`` structure contains
+important information about the memory used by the array (pointed to
+by the data member) This flag information must be kept accurate or
+strange results and even segfaults may result.
+
+There are 6 (binary) flags that describe the memory area used by the
+data buffer.  These constants are defined in ``arrayobject.h`` and
+determine the bit-position of the flag.  Python exposes a nice
+attribute- based interface as well as a dictionary-like interface for
+getting (and, if appropriate, setting) these flags.
+
+Memory areas of all kinds can be pointed to by an ndarray,
+necessitating these flags.  If you get an arbitrary ``PyArrayObject``
+in C-code, you need to be aware of the flags that are set.  If you
+need to guarantee a certain kind of array (like ``NPY_CONTIGUOUS`` and
+``NPY_BEHAVED``), then pass these requirements into the
+PyArray_FromAny function.
+
 
 Basic Array Flags
 ^^^^^^^^^^^^^^^^^
@@ -1023,6 +1044,12 @@ associated with an array.
     The data area is in Fortran-style contiguous order (first index varies
     the fastest).
 
+Notice that contiguous 1-d arrays are always both ``NPY_FORTRAN``
+contiguous and C contiguous. Both of these flags can be checked and
+are convenience flags only as whether or not an array is
+``NPY_CONTIGUOUS`` or ``NPY_FORTRAN`` can be determined by the
+``strides``, ``dimensions``, and ``itemsize`` attributes.
+
 .. cvar:: NPY_OWNDATA
 
     The data area is owned by this array.
@@ -1043,6 +1070,24 @@ associated with an array.
     The data area represents a (well-behaved) copy whose information
     should be transferred back to the original when this array is deleted.
 
+    This is a special flag that is set if this array represents a copy
+    made because a user required certain flags in
+    :cfunc:`PyArray_FromAny` and a copy had to be made of some other
+    array (and the user asked for this flag to be set in such a
+    situation). The base attribute then points to the "misbehaved"
+    array (which is set read_only). When the array with this flag set
+    is deallocated, it will copy its contents back to the "misbehaved"
+    array (casting if necessary) and will reset the "misbehaved" array
+    to :cdata:`NPY_WRITEABLE`. If the "misbehaved" array was not
+    :cdata:`NPY_WRITEABLE` to begin with then :cfunc:`PyArray_FromAny`
+    would have returned an error because :cdata:`NPY_UPDATEIFCOPY`
+    would not have been possible.
+
+:cfunc:`PyArray_UpdateFlags` (obj, flags) will update the
+``obj->flags`` for ``flags`` which can be any of
+:cdata:`NPY_CONTIGUOUS`, :cdata:`NPY_FORTRAN`, :cdata:`NPY_ALIGNED`,
+or :cdata:`NPY_WRITEABLE`.
+
 
 Combinations of array flags
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1721,6 +1766,29 @@ Array Functions
     *op1*, 2 - return all possible shifts (any overlap at all is
     accepted).
 
+    .. rubric:: Notes
+
+    This does not compute the usual correlation: if op2 is larger than op1, the
+    arguments are swapped, and the conjugate is never taken for complex arrays.
+    See PyArray_Correlate2 for the usual signal processing correlation.
+
+.. cfunction:: PyObject* PyArray_Correlate2(PyObject* op1, PyObject* op2, int mode)
+
+    Updated version of PyArray_Correlate, which uses the usual definition of
+    correlation for 1d arrays. The correlation is computed at each output point
+    by multiplying *op1* by a shifted version of *op2* and summing the result.
+    As a result of the shift, needed values outside of the defined range of
+    *op1* and *op2* are interpreted as zero. The mode determines how many
+    shifts to return: 0 - return only shifts that did not need to assume zero-
+    values; 1 - return an object that is the same size as *op1*, 2 - return all
+    possible shifts (any overlap at all is accepted).
+
+    .. rubric:: Notes
+
+    Compute z as follows::
+
+      z[k] = sum_n op1[n] * conj(op2[n+k])
+
 .. cfunction:: PyObject* PyArray_Where(PyObject* condition, PyObject* x, PyObject* y)
 
     If both ``x`` and ``y`` are ``NULL``, then return
@@ -1901,6 +1969,96 @@ Broadcasting (multi-iterators)
     loop should be performed over the axis that won't require large
     stride jumps.
 
+Neighborhood iterator
+---------------------
+
+.. versionadded:: 1.4.0
+
+Neighborhood iterators are subclasses of the iterator object, and can be used
+to iter over a neighborhood of a point. For example, you may want to iterate
+over every voxel of a 3d image, and for every such voxel, iterate over an
+hypercube. Neighborhood iterator automatically handle boundaries, thus making
+this kind of code much easier to write than manual boundaries handling, at the
+cost of a slight overhead.
+
+.. cfunction:: PyObject* PyArray_NeighborhoodIterNew(PyArrayIterObject* iter, npy_intp bounds, int mode, PyArrayObject* fill_value)
+
+    This function creates a new neighborhood iterator from an existing
+    iterator.  The neighborhood will be computed relatively to the position
+    currently pointed by *iter*, the bounds define the shape of the
+    neighborhood iterator, and the mode argument the boundaries handling mode.
+
+    The *bounds* argument is expected to be a (2 * iter->ao->nd) arrays, such
+    as the range bound[2*i]->bounds[2*i+1] defines the range where to walk for
+    dimension i (both bounds are included in the walked coordinates). The
+    bounds should be ordered for each dimension (bounds[2*i] <= bounds[2*i+1]).
+
+    The mode should be one of:
+
+    * NPY_NEIGHBORHOOD_ITER_ZERO_PADDING: zero padding. Outside bounds values
+      will be 0.
+    * NPY_NEIGHBORHOOD_ITER_ONE_PADDING: one padding, Outside bounds values
+      will be 1.
+    * NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING: constant padding. Outside bounds
+      values will be the same as the first item in fill_value.
+    * NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING: mirror padding. Outside bounds
+      values will be as if the array items were mirrored. For example, for the
+      array [1, 2, 3, 4], x[-2] will be 2, x[-2] will be 1, x[4] will be 4,
+      x[5] will be 1, etc...
+    * NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING: circular padding. Outside bounds
+      values will be as if the array was repeated. For example, for the
+      array [1, 2, 3, 4], x[-2] will be 3, x[-2] will be 4, x[4] will be 1,
+      x[5] will be 2, etc...
+
+    If the mode is constant filling (NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING),
+    fill_value should point to an array object which holds the filling value
+    (the first item will be the filling value if the array contains more than
+    one item). For other cases, fill_value may be NULL.
+
+    - The iterator holds a reference to iter
+    - Return NULL on failure (in which case the reference count of iter is not
+      changed)
+    - iter itself can be a Neighborhood iterator: this can be useful for .e.g
+      automatic boundaries handling
+    - the object returned by this function should be safe to use as a normal
+      iterator
+    - If the position of iter is changed, any subsequent call to
+      PyArrayNeighborhoodIter_Next is undefined behavior, and
+      PyArrayNeighborhoodIter_Reset must be called.
+
+    .. code-block:: c
+
+       PyArrayIterObject \*iter;
+       PyArrayNeighborhoodIterObject \*neigh_iter;
+       iter = PyArray_IterNew(x);
+
+       //For a 3x3 kernel
+       bounds = {-1, 1, -1, 1};
+       neigh_iter = (PyArrayNeighborhoodIterObject*)PyArrayNeighborhoodIter_New(
+            iter, bounds, NPY_NEIGHBORHOOD_ITER_ZERO_PADDING, NULL);
+
+       for(i = 0; i < iter->size; ++i) {
+            for (j = 0; j < neigh_iter->size; ++j) {
+                    // Walk around the item currently pointed by iter->dataptr
+                    PyArrayNeighborhoodIter_Next(neigh_iter);
+            }
+
+            // Move to the next point of iter
+            PyArrayIter_Next(iter);
+            PyArrayNeighborhoodIter_Reset(neigh_iter);
+       }
+
+.. cfunction:: int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter)
+
+    Reset the iterator position to the first point of the neighborhood. This
+    should be called whenever the iter argument given at
+    PyArray_NeighborhoodIterObject is changed (see example)
+
+.. cfunction:: int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter)
+
+    After this call, iter->dataptr points to the next point of the
+    neighborhood. Calling this function after every point of the
+    neighborhood has been visited is undefined.
 
 Array Scalars
 -------------
diff --git a/doc/source/reference/c-api.config.rst b/doc/source/reference/c-api.config.rst
index 0c7f6b147..0989c53d7 100644
--- a/doc/source/reference/c-api.config.rst
+++ b/doc/source/reference/c-api.config.rst
@@ -89,8 +89,8 @@ Platform information
     .. versionadded:: 1.3.0
 
     Portable alternatives to the ``endian.h`` macros of GNU Libc.
-    One of :cdata:`NPY_BIG_ENDIAN` :cdata:`NPY_LITTLE_ENDIAN` or
-    is defined, and :cdata:`NPY_BYTE_ORDER` is either 4321 or 1234.
+    If big endian, :cdata:`NPY_BYTE_ORDER` == :cdata:`NPY_BIG_ENDIAN`, and
+    similarly for little endian architectures.
 
     Defined in ``numpy/npy_endian.h``.
 
diff --git a/doc/source/reference/c-api.coremath.rst b/doc/source/reference/c-api.coremath.rst
index 8e6011603..b1a356551 100644
--- a/doc/source/reference/c-api.coremath.rst
+++ b/doc/source/reference/c-api.coremath.rst
@@ -69,6 +69,14 @@ Floating point classification
     and extended precision, and return a non 0 value is x has the signbit set
     (that is the number is negative).
 
+.. cfunction:: double npy_copysign(double x, double y)
+
+    This is a function equivalent to C99 copysign: return x with the same sign
+    as y. Works for any value, including inf and nan. Single and extended
+    precisions are available with suffix f and l.
+
+    .. versionadded:: 1.4.0
+
 Useful math constants
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -114,3 +122,22 @@ precision are also available by adding the F and L suffixes respectively.
 .. cvar:: NPY_2_PI
 
     Two times the reciprocal of pi (:math:`\frac{2}{\pi}`)
+
+.. cvar:: NPY_EULER
+
+    The Euler constant (:math:`\lim_{n\rightarrow \infty}{\sum_{k=1}^n{\frac{1}{k}} - \ln n}`)
+
+Linking against the core math library in an extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.4.0
+
+To use the core math library in your own extension, you need to add the npymath
+compile and link options to your extension in your setup.py:
+
+        >>> from numpy.distutils.misc_utils import get_info
+        >>> info = get_info('npymath')
+        >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)
+
+In other words, the usage of info is exactly the same as when using blas_info
+and co.
diff --git a/doc/source/reference/generalized_ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst
index d9f3818b9..870e5dbc4 100644
--- a/doc/source/reference/generalized_ufuncs.rst
+++ b/doc/source/reference/c-api.generalized-ufuncs.rst
@@ -1,6 +1,6 @@
-===============================
-Generalized Universal Functions
-===============================
+==================================
+Generalized Universal Function API
+==================================
 
 There is a general need for looping over not only functions on scalars
 but also over functions on vectors (or arrays), as explained on
@@ -91,14 +91,14 @@ dimensions.  The signature is represented by a string of the
 following format:
 
 * Core dimensions of each input or output array are represented by a
-  list of dimension names in parentheses, ``(i_1,...,i_N)``; a scalar 
+  list of dimension names in parentheses, ``(i_1,...,i_N)``; a scalar
   input/output is denoted by ``()``.  Instead of ``i_1``, ``i_2``,
   etc, one can use any valid Python variable name.
 * Dimension lists for different arguments are separated by ``","``.
   Input/output arguments are separated by ``"->"``.
 * If one uses the same dimension name in multiple locations, this
   enforces the same size (or broadcastable size) of the corresponding
-  dimensions.  
+  dimensions.
 
 The formal syntax of signatures is as follows::
 
diff --git a/doc/source/reference/c-api.rst b/doc/source/reference/c-api.rst
index 158e04a16..9bcc68b49 100644
--- a/doc/source/reference/c-api.rst
+++ b/doc/source/reference/c-api.rst
@@ -45,4 +45,5 @@ code.
    c-api.dtype
    c-api.array
    c-api.ufunc
+   c-api.generalized-ufuncs
    c-api.coremath
diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst
index b99702e11..ece7f341b 100644
--- a/doc/source/reference/c-api.types-and-structures.rst
+++ b/doc/source/reference/c-api.types-and-structures.rst
@@ -917,6 +917,18 @@ PyArrayMultiIter_Type
        to be broadcast together. On return, the iterators are adjusted for
        broadcasting.
 
+PyArrayNeighborhoodIter_Type
+----------------------------
+
+.. cvar:: PyArrayNeighborhoodIter_Type
+
+   This is an iterator object that makes it easy to loop over an N-dimensional
+   neighborhood.
+
+.. ctype:: PyArrayNeighborhoodIterObject
+
+   The C-structure corresponding to an object of :cdata:`PyArrayNeighborhoodIter_Type` is
+   the :ctype:`PyArrayNeighborhoodIterObject`.
 
 PyArrayFlags_Type
 -----------------
diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst
index bd0ee8e02..6a6a0dff0 100644
--- a/doc/source/reference/c-api.ufunc.rst
+++ b/doc/source/reference/c-api.ufunc.rst
@@ -70,43 +70,45 @@ Functions
     operation. Each ufunc object contains pointers to 1-d loops
     implementing the basic functionality for each supported type.
 
-    :param nin:
-
-        The number of inputs to this operation.
-
-    :param nout:
-
-        The number of outputs
-
-    :param ntypes:
+    .. note::
 
-        How many different data-type "signatures" the ufunc has implemented.
+       The *func*, *data*, *types*, *name*, and *doc* arguments are not
+       copied by :cfunc:`PyUFunc_FromFuncAndData`. The caller must ensure
+       that the memory used by these arrays is not freed as long as the
+       ufunc object is alive.
 
     :param func:
-
         Must to an array of length *ntypes* containing
         :ctype:`PyUFuncGenericFunction` items. These items are pointers to
-        functions that acutally implement the underlying
-        (element-by-element) function :math:`N` times. T
+        functions that actually implement the underlying
+        (element-by-element) function :math:`N` times.
 
-    :param types:
+    :param data:
+        Should be ``NULL`` or a pointer to an array of size *ntypes*
+        . This array may contain arbitrary extra-data to be passed to
+        the corresponding 1-d loop function in the func array.
 
+    :param types:
         Must be of length (*nin* + *nout*) \* *ntypes*, and it
         contains the data-types (built-in only) that the corresponding
         function in the *func* array can deal with.
 
-    :param data:
+    :param ntypes:
+        How many different data-type "signatures" the ufunc has implemented.
 
-        Should be ``NULL`` or a pointer to an array of size *ntypes*
-        . This array may contain arbitrary extra-data to be passed to
-        the corresponding 1-d loop function in the func array.
+    :param nin:
+        The number of inputs to this operation.
 
-    :param name:
+    :param nout:
+        The number of outputs
 
+    :param identity:
+        XXX: Undocumented
+
+    :param name:
         The name for the ufunc.
 
     :param doc:
-
         Allows passing in a documentation string to be stored with the
         ufunc.  The documentation string should not contain the name
         of the function or the calling signature as that will be
@@ -114,7 +116,6 @@ Functions
         accessing the **__doc__** attribute of the ufunc.
 
     :param check_return:
-
         Unused and present for backwards compatibility of the C-API. A
         corresponding *check_return* integer does exist in the ufunc
         structure and it does get set with this value when the ufunc
diff --git a/doc/source/reference/distutils.rst b/doc/source/reference/distutils.rst
index 051a1c031..bb01a529a 100644
--- a/doc/source/reference/distutils.rst
+++ b/doc/source/reference/distutils.rst
@@ -67,223 +67,49 @@ misc_util
     files in the numpy distribution are good examples of how to use
     the :class:`Configuration` instance.
 
-    .. method:: todict()
-
-        Return a dictionary compatible with the keyword arguments of distutils
-        setup function. Thus, this method may be used as
-        setup(\**config.todict()).
-
-    .. method:: get_distribution()
-
-        Return the distutils distribution object for self.
-
-    .. method:: get_subpackage(subpackage_name, subpackage_path=None)
-
-        Return a Configuration instance for the sub-package given. If
-        subpackage_path is None then the path is assumed to be the local path
-        plus the subpackage_name. If a setup.py file is not found in the
-        subpackage_path, then a default configuration is used.
-
-    .. method:: add_subpackage(subpackage_name, subpackage_path=None)
-
-        Add a sub-package to the current Configuration instance. This is
-        useful in a setup.py script for adding sub-packages to a package. The
-        sub-package is contained in subpackage_path / subpackage_name and this
-        directory may contain a setup.py script or else a default setup
-        (suitable for Python-code-only subpackages) is assumed. If the
-        subpackage_path is None, then it is assumed to be located in the local
-        path / subpackage_name.
-
-    .. method:: self.add_data_files(*files)
-
-        Add files to the list of data_files to be included with the package.
-        The form of each element of the files sequence is very flexible
-        allowing many combinations of where to get the files from the package
-        and where they should ultimately be installed on the system. The most
-        basic usage is for an element of the files argument sequence to be a
-        simple filename. This will cause that file from the local path to be
-        installed to the installation path of the self.name package (package
-        path). The file argument can also be a relative path in which case the
-        entire relative path will be installed into the package directory.
-        Finally, the file can be an absolute path name in which case the file
-        will be found at the absolute path name but installed to the package
-        path.
-
-        This basic behavior can be augmented by passing a 2-tuple in as the
-        file argument. The first element of the tuple should specify the
-        relative path (under the package install directory) where the
-        remaining sequence of files should be installed to (it has nothing to
-        do with the file-names in the source distribution). The second element
-        of the tuple is the sequence of files that should be installed. The
-        files in this sequence can be filenames, relative paths, or absolute
-        paths. For absolute paths the file will be installed in the top-level
-        package installation directory (regardless of the first argument).
-        Filenames and relative path names will be installed in the package
-        install directory under the path name given as the first element of
-        the tuple. An example may clarify::
-
-            self.add_data_files('foo.dat',
-            ('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']),
-            'bar/cat.dat',
-            '/full/path/to/can.dat')
-
-        will install these data files to::
-
-            <package install directory>/
-             foo.dat
-             fun/
-               gun.dat
-               nun/
-                 pun.dat
-             sun.dat
-             bar/
-               car.dat
-             can.dat
-
-        where <package install directory> is the package (or sub-package)
-        directory such as '/usr/lib/python2.4/site-packages/mypackage' ('C: \\Python2.4 \\Lib \\site-packages \\mypackage') or '/usr/lib/python2.4/site-
-        packages/mypackage/mysubpackage' ('C: \\Python2.4 \\Lib \\site-packages \\mypackage \\mysubpackage').
-
-
-        An additional feature is that the path to a data-file can actually be
-        a function that takes no arguments and returns the actual path(s) to
-        the data-files. This is useful when the data files are generated while
-        building the package.
-
-    .. method:: add_data_dir(data_path)
-
-        Recursively add files under data_path to the list of data_files to be
-        installed (and distributed). The data_path can be either a relative
-        path-name, or an absolute path-name, or a 2-tuple where the first
-        argument shows where in the install directory the data directory
-        should be installed to. For example suppose the source directory
-        contains fun/foo.dat and fun/bar/car.dat::
-
-            self.add_data_dir('fun')
-            self.add_data_dir(('sun', 'fun'))
-            self.add_data_dir(('gun', '/full/path/to/fun'))
-
-        Will install data-files to the locations::
-
-            <package install directory>/
-              fun/
-                foo.dat
-                bar/
-                  car.dat
-              sun/
-                foo.dat
-                bar/
-                  car.dat
-              gun/
-                foo.dat
-                car.dat
-
-    .. method:: add_include_dirs(*paths)
-
-        Add the given sequence of paths to the beginning of the include_dirs
-        list. This list will be visible to all extension modules of the
-        current package.
-
-    .. method:: add_headers(*files)
-
-        Add the given sequence of files to the beginning of the headers list.
-        By default, headers will be installed under <python-
-        include>/<self.name.replace('.','/')>/ directory. If an item of files
-        is a tuple, then its first argument specifies the actual installation
-        location relative to the <python-include> path.
-
-    .. method:: add_extension(name, sources, **kw)
-
-        Create and add an Extension instance to the ext_modules list. The
-        first argument defines the name of the extension module that will be
-        installed under the self.name package. The second argument is a list
-        of sources. This method also takes the following optional keyword
-        arguments that are passed on to the Extension constructor:
-        include_dirs, define_macros, undef_macros, library_dirs, libraries,
-        runtime_library_dirs, extra_objects, swig_opts, depends, language,
-        f2py_options, module_dirs, and extra_info.
-
-        The self.paths(...) method is applied to all lists that may contain
-        paths. The extra_info is a dictionary or a list of dictionaries whose
-        content will be appended to the keyword arguments. The depends list
-        contains paths to files or directories that the sources of the
-        extension module depend on. If any path in the depends list is newer
-        than the extension module, then the module will be rebuilt.
-
-        The list of sources may contain functions (called source generators)
-        which must take an extension instance and a build directory as inputs
-        and return a source file or list of source files or None. If None is
-        returned then no sources are generated. If the Extension instance has
-        no sources after processing all source generators, then no extension
-        module is built.
+    .. automethod:: todict
 
-    .. method:: add_library(name, sources, **build_info)
+    .. automethod:: get_distribution
 
-        Add a library to the list of libraries. Allowed keyword arguments are
-        depends, macros, include_dirs, extra_compiler_args, and f2py_options.
-        The name is the name of the library to be built and sources is a list
-        of sources (or source generating functions) to add to the library.
+    .. automethod:: get_subpackage
 
-    .. method:: add_scripts(*files)
+    .. automethod:: add_subpackage
 
-        Add the sequence of files to the beginning of the scripts list.
-        Scripts will be installed under the <prefix>/bin/ directory.
+    .. automethod:: add_data_files
 
-    .. method:: paths(*paths)
+    .. automethod:: add_data_dir
 
-        Applies glob.glob(...) to each path in the sequence (if needed) and
-        pre-pends the local_path if needed. Because this is called on all
-        source lists, this allows wildcard characters to be specified in lists
-        of sources for extension modules and libraries and scripts and allows
-        path-names be relative to the source directory.
+    .. automethod:: add_include_dirs
 
-    .. method:: get_config_cmd()
+    .. automethod:: add_headers
 
-        Returns the numpy.distutils config command instance.
+    .. automethod:: add_extension
 
-    .. method:: get_build_temp_dir()
+    .. automethod:: add_library
 
-        Return a path to a temporary directory where temporary files should be
-        placed.
+    .. automethod:: add_scripts
 
-    .. method:: have_f77c()
+    .. automethod:: add_installed_library
 
-        True if a Fortran 77 compiler is available (because a simple Fortran
-        77 code was able to be compiled successfully).
+    .. automethod:: add_npy_pkg_config
 
-    .. method:: have_f90c()
+    .. automethod:: paths
 
-        True if a Fortran 90 compiler is available (because a simple Fortran
-        90 code was able to be compiled successfully)
+    .. automethod:: get_config_cmd
 
-    .. method:: get_version()
+    .. automethod:: get_build_temp_dir
 
-        Return a version string of the current package or None if the version
-        information could not be detected. This method scans files named
-        __version__.py, <packagename>_version.py, version.py, and
-        __svn_version__.py for string variables version, __version\__, and
-        <packagename>_version, until a version number is found.
+    .. automethod:: have_f77c
 
-    .. method:: make_svn_version_py()
+    .. automethod:: have_f90c
 
-        Appends a data function to the data_files list that will generate
-        __svn_version__.py file to the current package directory. This file
-        will be removed from the source directory when Python exits (so that
-        it can be re-generated next time the package is built). This is
-        intended for working with source directories that are in an SVN
-        repository.
+    .. automethod:: get_version
 
-    .. method:: make_config_py()
+    .. automethod:: make_svn_version_py
 
-        Generate a package __config__.py file containing system information
-        used during the building of the package. This file is installed to the
-        package installation directory.
-
-    .. method:: get_info(*names)
-
-        Return information (from system_info.get_info) for all of the names in
-        the argument list in a single dictionary.
+    .. automethod:: make_config_py
 
+    .. automethod:: get_info
 
 Other modules
 -------------
@@ -299,6 +125,83 @@ Other modules
    log.set_verbosity
    exec_command
 
+Building Installable C libraries
+================================
+
+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::
+
+  >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
+
+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
+similar to .pc files as used by the pkg-config unix utility::
+
+  [meta]
+  Name: foo
+  Version: 1.0
+  Description: foo library
+
+  [variables]
+  prefix = /home/user/local
+  libdir = ${prefix}/lib
+  includedir = ${prefix}/include
+
+  [default]
+  cflags = -I${includedir}
+  libs = -L${libdir} -lfoo
+
+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
+template file foo.ini.in as follows::
+
+  [meta]
+  Name: foo
+  Version: @version@
+  Description: foo library
+
+  [variables]
+  prefix = @prefix@
+  libdir = ${prefix}/lib
+  includedir = ${prefix}/include
+
+  [default]
+  cflags = -I${includedir}
+  libs = -L${libdir} -lfoo
+
+and the following code in setup.py::
+
+  >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
+  >>> subst = {'version': '1.0'}
+  >>> 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
+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.
+
+Reusing a C library from another package
+----------------------------------------
+
+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.
 
 Conversion of ``.src`` files
 ============================
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 0d83053ac..00317a18e 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -19,7 +19,6 @@ For learning how to use NumPy, see also :ref:`user`.
 
    arrays
    ufuncs
-   generalized_ufuncs
    routines
    ctypes
    distutils
@@ -37,8 +36,6 @@ the functions are written by numerous contributors and developers of
 Numpy, both prior to and during the
 `Numpy Documentation Marathon <http://scipy.org/Developer_Zone/DocMarathon2008>`__.
 
-The Documentation Marathon is still ongoing. Please help us write
-better documentation for Numpy by joining it! Instructions on how to
-join and what to do can be found
+Please help to improve NumPy's documentation! Instructions on how to
+join the ongoing documentation marathon can be found
 `on the scipy.org website <http://scipy.org/Developer_Zone/DocMarathon2008>`__
-
diff --git a/doc/source/reference/routines.indexing.rst b/doc/source/reference/routines.indexing.rst
index f618fa0a4..9d8fde882 100644
--- a/doc/source/reference/routines.indexing.rst
+++ b/doc/source/reference/routines.indexing.rst
@@ -21,6 +21,13 @@ Generating index arrays
    ix_
    ogrid
    unravel_index
+   diag_indices
+   diag_indices_from
+   mask_indices
+   tril_indices
+   tril_indices_from
+   triu_indices
+   triu_indices_from
 
 Indexing-like operations
 ------------------------
@@ -42,6 +49,7 @@ Inserting data into arrays
    place
    put
    putmask
+   fill_diagonal
 
 Iterating over arrays
 ---------------------
diff --git a/doc/source/reference/routines.set.rst b/doc/source/reference/routines.set.rst
index 4c298e80f..27c6aeb89 100644
--- a/doc/source/reference/routines.set.rst
+++ b/doc/source/reference/routines.set.rst
@@ -8,16 +8,15 @@ Making proper sets
 .. autosummary::
    :toctree: generated/
 
-   unique1d
+   unique
 
 Boolean operations
 ------------------
 .. autosummary::
    :toctree: generated/
 
+   in1d
    intersect1d
-   intersect1d_nu
    setdiff1d
-   setmember1d
    setxor1d
    union1d
diff --git a/doc/source/reference/routines.statistics.rst b/doc/source/reference/routines.statistics.rst
index b41b62839..578cbd09a 100644
--- a/doc/source/reference/routines.statistics.rst
+++ b/doc/source/reference/routines.statistics.rst
@@ -35,6 +35,7 @@ Correlating
    :toctree: generated/
 
    corrcoef
+   acorrelate
    correlate
    cov
 
diff --git a/doc/source/reference/routines.testing.rst b/doc/source/reference/routines.testing.rst
index 5a5f4cb8c..075c1e3a9 100644
--- a/doc/source/reference/routines.testing.rst
+++ b/doc/source/reference/routines.testing.rst
@@ -29,6 +29,7 @@ Decorators
 .. autosummary::
    :toctree: generated/
 
+   decorators.deprecated
    decorators.knownfailureif
    decorators.setastest
    decorators.skipif
diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index d63486342..8096e1497 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -102,19 +102,24 @@ Output type determination
 The output of the ufunc (and its methods) is not necessarily an
 :class:`ndarray`, if all input arguments are not :class:`ndarrays <ndarray>`.
 
-All output arrays will be passed to the :obj:`__array_wrap__`
-method of the input (besides :class:`ndarrays <ndarray>`, and scalars)
-that defines it **and** has the highest :obj:`__array_priority__` of
-any other input to the universal function. The default
-:obj:`__array_priority__` of the ndarray is 0.0, and the default
-:obj:`__array_priority__` of a subtype is 1.0. Matrices have
-:obj:`__array_priority__` equal to 10.0.
+All output arrays will be passed to the :obj:`__array_prepare__` and
+:obj:`__array_wrap__` methods of the input (besides
+:class:`ndarrays <ndarray>`, and scalars) that defines it **and** has
+the highest :obj:`__array_priority__` of any other input to the
+universal function. The default :obj:`__array_priority__` of the
+ndarray is 0.0, and the default :obj:`__array_priority__` of a subtype
+is 1.0. Matrices have :obj:`__array_priority__` equal to 10.0.
 
 The ufuncs can also all take output arguments. The output will be cast
 if necessary to the provided output array. If a class with an
 :obj:`__array__` method is used for the output, results will be
 written to the object returned by :obj:`__array__`. Then, if the class
-also has an :obj:`__array_wrap__` method, the returned
+also has an :obj:`__array_prepare__` method, it is called so metadata
+may be determined based on the context of the ufunc (the context
+consisting of the ufunc itself, the arguments passed to the ufunc, and
+the ufunc domain.) The array object returned by
+:obj:`__array_prepare__` is passed to the ufunc for computation.
+Finally, if the class also has an :obj:`__array_wrap__` method, the returned
 :class:`ndarray` result will be passed to that method just before
 passing control back to the caller.
 
@@ -549,6 +554,7 @@ single operation.
     isinf
     isnan
     signbit
+    copysign
     modf
     ldexp
     frexp