# HG changeset patch
# User Matti Picus <matti.picus@gmail.com>
# Date 1509209621 -10800
#      Sat Oct 28 19:53:41 2017 +0300
# Branch extradoc
# Node ID 97b16db806afb7cc98b1e62b1e3a0c2ae1475498
# Parent  275468ee16dccf02cab00c60f254428ee6905427
update numpy installation info, refering to the FAQ answer in docs.pypy.org

diff --git a/download.html b/download.html
--- a/download.html
+++ b/download.html
@@ -212,38 +212,30 @@
 </div>
 <div class="section" id="installing-numpy">
 <h1>Installing NumPy</h1>
-<p><strong>There are two different versions of NumPy for PyPy.</strong></p>
-<div class="section" id="numpy-via-cpyext">
-<h2>1. NumPy via cpyext</h2>
-<p>The generally recommended way is to install the original NumPy via the
-CPython C API compatibility layer, cpyext.  Modern versions of PyPy
-support enough of the C API to make this a reasonable choice in many
-cases.  Performance-wise, the speed is mostly the same as CPython's
-NumPy (it is the same code); the exception is that interactions between
-the Python side and NumPy objects are mediated through the slower cpyext
-layer (which hurts a few benchmarks that do a lot of element-by-element
-array accesses, for example).</p>
-<p>Installation works on any recent PyPy (the <a class="reference internal" href="#release">release</a> above is fine, a recent
-nightly will implement more of the new buffer protocol).
-The currently released numpy 1.12 works except for <tt class="docutils literal">nditers</tt> with the
+<p><strong>There are two different versions of NumPy for PyPy.</strong> For details see this
+<a class="reference external" href="http://doc.pypy.org/en/latest/faq.html#should-i-install-numpy-or-numpypy">FAQ question</a>.</p>
+<div class="section" id="standard-numpy">
+<h2>1. Standard NumPy</h2>
+<p>Installation works on any recent PyPy (the <a class="reference internal" href="#release">release</a> above is fine).
+The currently released numpy 1.13 works except for <tt class="docutils literal">nditers</tt> with the
 <tt class="docutils literal">updateifcopy</tt> flag.
 For example, without using a virtualenv:</p>
 <pre class="literal-block">
 $ ./pypy-xxx/bin/pypy -m ensurepip
-$ ./pypy-xxx/bin/pypy -mpip install -U wheel # to update wheel
 $ ./pypy-xxx/bin/pip install cython numpy
 </pre>
 <p>(See the general <a class="reference external" href="http://doc.pypy.org/en/latest/install.html">installation documentation</a> for more.)</p>
 </div>
 <div class="section" id="numpypy">
 <h2>2. NumPyPy</h2>
-<p>The &ldquo;numpy&rdquo; module can be installed from <a class="reference external" href="https://bitbucket.org/pypy/numpy">our own repository</a> rather
-than from the official source.  This version uses internally our
-built-in <tt class="docutils literal">_numpypy</tt> module.  This module is slightly incomplete.
-Also, its performance is hard to predict exactly.  For regular NumPy
+<p>The &ldquo;numpy&rdquo; module can also be installed from <a class="reference external" href="https://bitbucket.org/pypy/numpy">our own repository</a> rather
+than from the official source.  This version uses our
+built-in <tt class="docutils literal">_numpypy</tt> multiarray replacement module, written in RPython.
+This module is not complete, but if it works it should give correct answers.
+Its performance is hard to predict exactly.  For regular NumPy
 source code that handles large arrays, it is likely to be slower than
-the native NumPy with cpyext.  It is faster on the kind of code that
-contains many Python loops doing things on an element-by-element basis.</p>
+the standard NumPy.  It is faster on pure python code that loop over ndarrays
+doing things on an element-by-element basis.</p>
 <p>Installation (see the <a class="reference external" href="http://doc.pypy.org/en/latest/install.html">installation documentation</a> for installing <tt class="docutils literal">pip</tt>):</p>
 <pre class="literal-block">
 pypy -m pip install git+https://bitbucket.org/pypy/numpy.git
@@ -258,9 +250,10 @@
 <pre class="literal-block">
 sudo pypy -c 'import numpy'
 </pre>
-<p>Note again that this version is still a work-in-progress: many things do
+<p>Note again that this version is incomplete: many things do
 not work and those that do may not be any faster than NumPy on CPython.
-For further instructions see <a class="reference external" href="https://bitbucket.org/pypy/numpy">the pypy/numpy repository</a>.</p>
+For further instructions see <a class="reference external" href="https://bitbucket.org/pypy/numpy">the pypy/numpy repository</a> and the
+<a class="reference external" href="http://doc.pypy.org/en/latest/faq.html#should-i-install-numpy-or-numpypy">FAQ question</a> about the difference between the two.</p>
 </div>
 </div>
 <div class="section" id="building-from-source">
diff --git a/source/download.txt b/source/download.txt
--- a/source/download.txt
+++ b/source/download.txt
@@ -223,29 +223,18 @@
 Installing NumPy
 -------------------------------
 
-**There are two different versions of NumPy for PyPy.**
-
-
-1. NumPy via cpyext
-+++++++++++++++++++
+**There are two different versions of NumPy for PyPy.** For details see this
+`FAQ question`_.
 
-The generally recommended way is to install the original NumPy via the
-CPython C API compatibility layer, cpyext.  Modern versions of PyPy
-support enough of the C API to make this a reasonable choice in many
-cases.  Performance-wise, the speed is mostly the same as CPython's
-NumPy (it is the same code); the exception is that interactions between
-the Python side and NumPy objects are mediated through the slower cpyext
-layer (which hurts a few benchmarks that do a lot of element-by-element
-array accesses, for example).
+1. Standard NumPy
++++++++++++++++++
 
-Installation works on any recent PyPy (the release_ above is fine, a recent
-nightly will implement more of the new buffer protocol).
-The currently released numpy 1.12 works except for ``nditers`` with the
+Installation works on any recent PyPy (the release_ above is fine).
+The currently released numpy 1.13 works except for ``nditers`` with the
 ``updateifcopy`` flag.
 For example, without using a virtualenv::
 
     $ ./pypy-xxx/bin/pypy -m ensurepip
-    $ ./pypy-xxx/bin/pypy -mpip install -U wheel # to update wheel
     $ ./pypy-xxx/bin/pip install cython numpy
 
 (See the general `installation documentation`_ for more.)
@@ -254,13 +243,14 @@
 2. NumPyPy
 ++++++++++
 
-The "numpy" module can be installed from `our own repository`__ rather
-than from the official source.  This version uses internally our
-built-in ``_numpypy`` module.  This module is slightly incomplete.
-Also, its performance is hard to predict exactly.  For regular NumPy
+The "numpy" module can also be installed from `our own repository`__ rather
+than from the official source.  This version uses our
+built-in ``_numpypy`` multiarray replacement module, written in RPython.
+This module is not complete, but if it works it should give correct answers.
+Its performance is hard to predict exactly.  For regular NumPy
 source code that handles large arrays, it is likely to be slower than
-the native NumPy with cpyext.  It is faster on the kind of code that
-contains many Python loops doing things on an element-by-element basis.
+the standard NumPy.  It is faster on pure python code that loop over ndarrays
+doing things on an element-by-element basis.
 
 .. __: https://bitbucket.org/pypy/numpy
 
@@ -278,11 +268,13 @@
 
     sudo pypy -c 'import numpy'
 
-Note again that this version is still a work-in-progress: many things do
+Note again that this version is incomplete: many things do
 not work and those that do may not be any faster than NumPy on CPython.
-For further instructions see `the pypy/numpy repository`__.
+For further instructions see `the pypy/numpy repository`__ and the
+`FAQ question`_ about the difference between the two.
 
 .. __: https://bitbucket.org/pypy/numpy
+.. _`FAQ question`: http://doc.pypy.org/en/latest/faq.html#should-i-install-numpy-or-numpypy
 
 
 .. _translate: