updated documentation from pydoc website (thanks to everyone who contributed!)

10 files changed, 69 insertions, 87 deletions

diff --git a/doc/source/user/basics.indexing.rst b/doc/source/user/basics.indexing.rst
index f218fd060..8844adcae 100644
--- a/doc/source/user/basics.indexing.rst
+++ b/doc/source/user/basics.indexing.rst
@@ -6,11 +6,4 @@ Indexing
 
 .. seealso:: :ref:`Indexing routines <routines.indexing>`
 
-.. note::
-
-   XXX: Combine ``numpy.doc.indexing`` with material
-   section 2.2 Basic indexing?
-   Or incorporate the material directly here?
-
-
 .. automodule:: numpy.doc.indexing
diff --git a/doc/source/user/basics.rec.rst b/doc/source/user/basics.rec.rst
index 81a3de8e3..ce6c3b851 100644
--- a/doc/source/user/basics.rec.rst
+++ b/doc/source/user/basics.rec.rst
@@ -1,3 +1,5 @@
+.. _structured_arrays:
+
 ***************************************
 Structured arrays (aka "Record arrays")
 ***************************************
diff --git a/doc/source/user/basics.rst b/doc/source/user/basics.rst
index 85e79c25d..bbc3ab174 100644
--- a/doc/source/user/basics.rst
+++ b/doc/source/user/basics.rst
@@ -2,11 +2,6 @@
 Numpy basics
 ************
 
-.. note::
-
-   XXX: there is overlap between this text extracted from ``numpy.doc``
-   and "Guide to Numpy" chapter 2. Needs combining?
-
 .. toctree::
    :maxdepth: 2
 
diff --git a/doc/source/user/basics.types.rst b/doc/source/user/basics.types.rst
index 4982045a2..5ce5af15a 100644
--- a/doc/source/user/basics.types.rst
+++ b/doc/source/user/basics.types.rst
@@ -4,11 +4,4 @@ Data types
 
 .. seealso:: :ref:`Data type objects <arrays.dtypes>`
 
-.. note::
-
-   XXX: Combine ``numpy.doc.indexing`` with material from
-   "Guide to Numpy" (section 2.1 Data-Type descriptors)?
-   Or incorporate the material directly here?
-
-
 .. automodule:: numpy.doc.basics
diff --git a/doc/source/user/c-info.beyond-basics.rst b/doc/source/user/c-info.beyond-basics.rst
index 703124b58..563467e72 100644
--- a/doc/source/user/c-info.beyond-basics.rst
+++ b/doc/source/user/c-info.beyond-basics.rst
@@ -159,17 +159,18 @@ Broadcasting over multiple arrays
 .. index::
    single: broadcasting
 
-When multiple arrays are involved in an operation, you may want to use the same
-broadcasting rules that the math operations ( *i.e.* the ufuncs) use. This can
-be done easily using the :ctype:`PyArrayMultiIterObject`.  This is the object
-returned from the Python command numpy.broadcast and it is almost as easy to
-use from C. The function :cfunc:`PyArray_MultiIterNew` ( ``n``, ``...`` ) is
-used (with ``n`` input objects in place of ``...`` ). The input objects can be
-arrays or anything that can be converted into an array. A pointer to a
-PyArrayMultiIterObject is returned.  Broadcasting has already been accomplished
-which adjusts the iterators so that all that needs to be done to advance to the
-next element in each array is for PyArray_ITER_NEXT to be called for each of
-the inputs. This incrementing is automatically performed by
+When multiple arrays are involved in an operation, you may want to use the
+same broadcasting rules that the math operations (*i.e.* the ufuncs) use.
+This can be done easily using the :ctype:`PyArrayMultiIterObject`.  This is
+the object returned from the Python command numpy.broadcast and it is almost
+as easy to use from C. The function
+:cfunc:`PyArray_MultiIterNew` ( ``n``, ``...`` ) is used (with ``n`` input
+objects in place of ``...`` ). The input objects can be arrays or anything
+that can be converted into an array. A pointer to a PyArrayMultiIterObject is
+returned.  Broadcasting has already been accomplished which adjusts the
+iterators so that all that needs to be done to advance to the next element in
+each array is for PyArray_ITER_NEXT to be called for each of the inputs. This
+incrementing is automatically performed by
 :cfunc:`PyArray_MultiIter_NEXT` ( ``obj`` ) macro (which can handle a
 multiterator ``obj`` as either a :ctype:`PyArrayMultiObject *` or a
 :ctype:`PyObject *`). The data from input number ``i`` is available using
@@ -233,15 +234,19 @@ can be used. The function call used to create a new ufunc to work on
 built-in data-types is given below. A different mechanism is used to
 register ufuncs for user-defined data-types.
 
-.. cfunction:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int check_return)
+.. cfunction:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func,
+   void** data, char* types, int ntypes, int nin, int nout, int identity,
+   char* name, char* doc, int check_return)
 
     *func*
 
         A pointer to an array of 1-d functions to use. This array must be at
-        least ntypes long. Each entry in the array must be a ``PyUFuncGenericFunction`` function. This function has the following signature. An example of a
-        valid 1d loop function is also given.
+        least ntypes long. Each entry in the array must be a
+        ``PyUFuncGenericFunction`` function. This function has the following
+        signature. An example of a valid 1d loop function is also given.
 
-        .. cfunction:: void loop1d(char** args, npy_intp* dimensions, npy_intp* steps, void* data)
+        .. cfunction:: void loop1d(char** args, npy_intp* dimensions,
+           npy_intp* steps, void* data)
 
         *args*
 
@@ -269,7 +274,8 @@ register ufuncs for user-defined data-types.
         .. code-block:: c
 
             static void
-            double_add(char *args, npy_intp *dimensions, npy_intp *steps, void *extra)
+            double_add(char *args, npy_intp *dimensions, npy_intp *steps,
+               void *extra)
             {
                 npy_intp i;
                 npy_intp is1=steps[0], is2=steps[1];
@@ -320,9 +326,9 @@ register ufuncs for user-defined data-types.
 
     *identity*
 
-        Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`, :cdata:`PyUFunc_None`.
-        This specifies what should be returned when an empty array is
-        passed to the reduce method of the ufunc.
+        Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`,
+        :cdata:`PyUFunc_None`. This specifies what should be returned when
+        an empty array is passed to the reduce method of the ufunc.
 
     *name*
 
@@ -458,7 +464,8 @@ functions for each conversion you want to support and then registering
 these functions with the data-type descriptor. A low-level casting
 function has the signature.
 
-.. cfunction:: void castfunc( void* from, void* to, npy_intp n, void* fromarr, void* toarr)
+.. cfunction:: void castfunc( void* from, void* to, npy_intp n, void* fromarr,
+   void* toarr)
 
     Cast ``n`` elements ``from`` one type ``to`` another. The data to
     cast from is in a contiguous, correctly-swapped and aligned chunk
@@ -531,7 +538,8 @@ previously created. Then you call :cfunc:`PyUFunc_RegisterLoopForType`
 this function is ``0`` if the process was successful and ``-1`` with
 an error condition set if it was not successful.
 
-.. cfunction:: int PyUFunc_RegisterLoopForType( PyUFuncObject* ufunc, int usertype, PyUFuncGenericFunction function, int* arg_types, void* data)
+.. cfunction:: int PyUFunc_RegisterLoopForType( PyUFuncObject* ufunc,
+   int usertype, PyUFuncGenericFunction function, int* arg_types, void* data)
 
     *ufunc*
 
@@ -661,10 +669,6 @@ Specific features of ndarray sub-typing
 Some special methods and attributes are used by arrays in order to
 facilitate the interoperation of sub-types with the base ndarray type.
 
-.. note:: XXX: some of the documentation below needs to be moved to the
-               reference guide.
-
-
 The __array_finalize\__ method
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/doc/source/user/c-info.python-as-glue.rst b/doc/source/user/c-info.python-as-glue.rst
index 4fb337821..6ce266859 100644
--- a/doc/source/user/c-info.python-as-glue.rst
+++ b/doc/source/user/c-info.python-as-glue.rst
@@ -13,7 +13,7 @@ Using Python as glue
 Many people like to say that Python is a fantastic glue language.
 Hopefully, this Chapter will convince you that this is true. The first
 adopters of Python for science were typically people who used it to
-glue together large applicaton codes running on super-computers. Not
+glue together large application codes running on super-computers. Not
 only was it much nicer to code in Python than in a shell script or
 Perl, in addition, the ability to easily extend Python made it
 relatively easy to create new classes and types specifically adapted
@@ -123,8 +123,7 @@ F2py allows you to automatically construct an extension module that
 interfaces to routines in Fortran 77/90/95 code. It has the ability to
 parse Fortran 77/90/95 code and automatically generate Python
 signatures for the subroutines it encounters, or you can guide how the
-subroutine interfaces with Python by constructing an interface-
-defintion-file (or modifying the f2py-produced one).
+subroutine interfaces with Python by constructing an interface-definition-file (or modifying the f2py-produced one).
 
 .. index::
    single: f2py
@@ -175,7 +174,7 @@ be imported from Python::
 This command leaves a file named add.{ext} in the current directory
 (where {ext} is the appropriate extension for a python extension
 module on your platform --- so, pyd, *etc.* ). This module may then be
-imported from Python. It will contain a method for each subroutin in
+imported from Python. It will contain a method for each subroutine in
 add (zadd, cadd, dadd, sadd). The docstring of each method contains
 information about how the module method may be called:
 
@@ -586,7 +585,7 @@ produce a robust but fast subroutine.
 
 One final note about weave.inline: if you have additional code you
 want to include in the final extension module such as supporting
-function calls, include statments, etc. you can pass this code in as a
+function calls, include statements, etc. you can pass this code in as a
 string using the keyword support_code: ``weave.inline(code, variables,
 support_code=support)``. If you need the extension module to link
 against an additional library then you can also pass in
@@ -784,7 +783,7 @@ details.
 Pyrex-filter
 ------------
 
-The two-dimensional example we created using weave is a bit uglierto
+The two-dimensional example we created using weave is a bit uglier to
 implement in Pyrex because two-dimensional indexing using Pyrex is not
 as simple. But, it is straightforward (and possibly faster because of
 pre-computed indices). Here is the Pyrex-file I named image.pyx.
@@ -873,7 +872,7 @@ There are several disadvantages of using Pyrex:
 4. Multi-dimensional arrays are "bulky" to index (appropriate macros
    may be able to fix this).
 
-5. The C-code generated by Prex is hard to read and modify (and typically
+5. The C-code generated by Pyrex is hard to read and modify (and typically
    compiles with annoying but harmless warnings).
 
 Writing a good Pyrex extension module still takes a bit of effort
@@ -1126,8 +1125,8 @@ significantly safer to call a C-function using ctypes and the data-
 area of an ndarray. You may still want to wrap the function in an
 additional Python wrapper to make it user-friendly (hiding some
 obvious arguments and making some arguments output arguments). In this
-process, the **requires** function in NumPy may be useful to return the right kind of array from
-a given input.
+process, the **requires** function in NumPy may be useful to return the right
+kind of array from a given input.
 
 
 Complete example
diff --git a/doc/source/user/howtofind.rst b/doc/source/user/howtofind.rst
index 5f6b49012..00ed5daa7 100644
--- a/doc/source/user/howtofind.rst
+++ b/doc/source/user/howtofind.rst
@@ -4,6 +4,4 @@ How to find documentation
 
 .. seealso:: :ref:`Numpy-specific help functions <routines.help>`
 
-.. note:: XXX: this part is not yet written.
-
 .. automodule:: numpy.doc.howtofind
diff --git a/doc/source/user/install.rst b/doc/source/user/install.rst
index 1941ebb29..06b2115da 100644
--- a/doc/source/user/install.rst
+++ b/doc/source/user/install.rst
@@ -12,29 +12,30 @@ 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>`_
+<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>`_.
+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.
+<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
 ====================
@@ -62,21 +63,22 @@ Building NumPy requires the following software installed:
 
 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.
+   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.
+   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
+   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
@@ -87,8 +89,8 @@ 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.
+*must* build numpy/scipy with gfortran. This applies for most other cases
+where different FORTRAN compilers might have been used.
 
 Choosing the fortran compiler
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -110,9 +112,9 @@ 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.
+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
 ---------------------------
diff --git a/doc/source/user/misc.rst b/doc/source/user/misc.rst
index 4e2ec9fdb..0e1807f3f 100644
--- a/doc/source/user/misc.rst
+++ b/doc/source/user/misc.rst
@@ -2,8 +2,6 @@
 Miscellaneous
 *************
 
-.. note:: XXX: This section is not yet written.
-
 .. automodule:: numpy.doc.misc
 
 .. automodule:: numpy.doc.methods_vs_functions
diff --git a/doc/source/user/performance.rst b/doc/source/user/performance.rst
index 1f6e4e16c..59f8a2edc 100644
--- a/doc/source/user/performance.rst
+++ b/doc/source/user/performance.rst
@@ -2,6 +2,4 @@
 Performance
 ***********
 
-.. note:: XXX: This section is not yet written.
-
 .. automodule:: numpy.doc.performance