Merge from doc wiki

9 files changed, 201 insertions, 52 deletions

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/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.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/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.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/user/index.rst b/doc/source/user/index.rst
index 8d8812c80..a9945a0d1 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -19,9 +19,9 @@ and classes, see :ref:`reference`.
 .. toctree::
    :maxdepth: 2
 
+   install
    howtofind
    basics
    performance
    misc
    c-info
-
diff --git a/doc/source/user/install.rst b/doc/source/user/install.rst
new file mode 100644
index 000000000..472ee20e3
--- /dev/null
+++ b/doc/source/user/install.rst
@@ -0,0 +1,148 @@
+*****************************
+Building and installing NumPy
+*****************************
+
+Binary installers
+=================
+
+In most use cases the best way to install NumPy on your system is by using an
+installable binary package for your operating system.
+
+Windows
+-------
+
+Good solutions for Windows are, The Enthought Python Distribution `(EPD)
+<http://www.enthought.com/products/epd.php>`_ (which provides binary installers
+for Windows, OS X and Redhat) and `Python (x, y) <http://www.pythonxy.com>`_.
+Both of these packages include Python, NumPy and many additional packages.
+A lightweight alternative is to download the Python installer from
+`www.python.org <http://www.python.org>`_ and the NumPy installer for your
+Python version from the Sourceforge `download site
+<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_
+
+Linux
+-----
+
+Most of the major distributions provide packages for NumPy, but these can lag
+behind the most recent NumPy release. Pre-built binary packages for Ubuntu are
+available on the `scipy ppa <https://edge.launchpad.net/~scipy/+archive/ppa>`_.
+Redhat binaries are available in the `EPD
+<http://www.enthought.com/products/epd.php>`_.
+
+Mac OS X
+--------
+
+A universal binary installer for NumPy is available from the `download site
+<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_.
+The `EPD <http://www.enthought.com/products/epd.php>`_ provides NumPy binaries.
+
+Building from source
+====================
+
+A general overview of building NumPy from source is given here, with detailed
+instructions for specific platforms given seperately.
+
+Prerequisites
+-------------
+
+Building NumPy requires the following software installed:
+
+1) Python 2.4.x, 2.5.x or 2.6.x
+
+   On Debian and derivative (Ubuntu): python, python-dev
+
+   On Windows: the official python installer at
+   `www.python.org <http://www.python.org>`_ is enough
+
+   Make sure that the Python package distutils is installed before
+   continuing. For example, in Debian GNU/Linux, distutils is included
+   in the python-dev package.
+
+   Python must also be compiled with the zlib module enabled.
+
+2) Compilers
+
+   To build any extension modules for Python, you'll need a C compiler.  Various
+   NumPy modules use FORTRAN 77 libraries, so you'll also need a FORTRAN 77
+   compiler installed.
+
+   Note that NumPy is developed mainly using GNU compilers. Compilers from other
+   vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland, Lahey, HP,
+   IBM, Microsoft are only supported in the form of community feedback, and may
+   not work out of the box. GCC 3.x (and later) compilers are recommended.
+
+3) Linear Algebra libraries
+
+   NumPy does not require any external linear algebra libraries to be installed.
+   However, if these are available, NumPy's setup script can detect them and use
+   them for building. A number of different LAPACK library setups can be used,
+   including optimized LAPACK libraries such as ATLAS, MKL or the
+   Accelerate/vecLib framework on OS X.
+
+FORTRAN ABI mismatch
+--------------------
+
+The two most popular open source fortran compilers are g77 and gfortran.
+Unfortunately, they are not ABI compatible, which means that concretely you
+should avoid mixing libraries built with one with another. In particular, if
+your blas/lapack/atlas is built with g77, you *must* use g77 when building
+numpy and scipy; on the contrary, if your atlas is built with gfortran, you
+*must* build numpy/scipy with gfortran. This applies for most other cases where
+different FORTRAN compilers might have been used.
+
+Choosing the fortran compiler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To build with g77:
+
+    python setup.py build --fcompiler=gnu
+
+To build with gfortran:
+
+    python setup.py build --fcompiler=gnu95
+
+For more information see:
+
+    python setup.py build --help-fcompiler
+
+How to check the ABI of blas/lapack/atlas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One relatively simple and reliable way to check for the compiler used to build
+a library is to use ldd on the library. If libg2c.so is a dependency, this
+means that g77 has been used. If libgfortran.so is a a dependency, gfortran has
+been used. If both are dependencies, this means both have been used, which is
+almost always a very bad idea.
+
+Building with ATLAS support
+---------------------------
+
+Ubuntu 8.10 (Intrepid)
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can install the necessary packages for optimized ATLAS with this command:
+
+    sudo apt-get install libatlas-base-dev
+
+If you have a recent CPU with SIMD suppport (SSE, SSE2, etc...), you should
+also install the corresponding package for optimal performances. For example,
+for SSE2:
+
+    sudo apt-get install libatlas3gf-sse2
+
+*NOTE*: if you build your own atlas, Intrepid changed its default fortran
+compiler to gfortran. So you should rebuild everything from scratch, including
+lapack, to use it on Intrepid.
+
+Ubuntu 8.04 and lower
+~~~~~~~~~~~~~~~~~~~~~
+
+You can install the necessary packages for optimized ATLAS with this command:
+
+    sudo apt-get install atlas3-base-dev
+
+If you have a recent CPU with SIMD suppport (SSE, SSE2, etc...), you should
+also install the corresponding package for optimal performances. For example,
+for SSE2:
+
+    sudo apt-get install atlas3-sse2