clarification: prefer for-in-range over for-from

diff --git a/docs/language_basics.rst b/docs/language_basics.rst
index 12348fdc525c5e407ba43e0a78e83d0bfde81fb8..082d21025d91f6c82d182da574d22e54076f652e 100644 (file)
--- a/docs/language_basics.rst
+++ b/docs/language_basics.rst
@@ -295,13 +295,21 @@ Python and C, and that Cython uses the Python precedences, not the C ones.
 Integer for-loops
 ------------------
 
-You should be aware that a for-loop such as::
+Cython recognises the usual Python for-in-range integer loop pattern::
 
     for i in range(n):
         ...
 
-won't be very fast if ``i`` is not a :keyword:`cdef` integer type.
-For iterating over ranges of integers, Cython has another form of for-loop::
+If ``i`` is declared as a :keyword:`cdef` integer type, it will
+optimise this into a pure C loop.  This restriction is required as
+otherwise the generated code wouldn't be correct due to potential
+integer overflows on the target architecture.  If you are worried that
+the loop is not being converted correctly, use the annotate feature of
+the cython commandline (``-a``) to easily see the generated C code.
+See :ref:`automatic-range-conversion`
+
+For backwards compatibility to Pyrex, Cython also supports another
+form of for-loop::
 
     for i from 0 <= i < n:
         ...
@@ -313,17 +321,6 @@ or::
 
 where ``s`` is some integer step size.
 
-If the loop variable and the lower and upper bounds are all C integers, this
-form of loop will be much faster, because Cython will translate it into pure C
-code. 
-
-.. note::
-    This is not necessary if ``i`` is a C integer type and ``n`` can be
-    determined at compile time. Just use the idiomatic :func:`range` loop, if
-    you are worried that the loop is not being converted correctly use the
-    annotate feature of the cython commandline (``-a``) to easily see the
-    generated C code. See :ref:`automatic-range-conversion`
-
 Some things to note about the for-from loop:
 
 * The target expression must be a variable name.