resolved conflicts

39 files changed, 679 insertions, 621 deletions

diff --git a/doc/source/f2py/advanced.rst b/doc/source/f2py/advanced.rst
index 1b4625dde..c8efbaadb 100644
--- a/doc/source/f2py/advanced.rst
+++ b/doc/source/f2py/advanced.rst
@@ -1,48 +1,46 @@
-======================
-Advanced F2PY usages
-======================
+========================
+Advanced F2PY use cases
+========================
 
-Adding self-written functions to F2PY generated modules
-=======================================================
+Adding user-defined functions to F2PY generated modules
+=========================================================
 
-Self-written Python C/API functions can be defined inside
+User-defined Python C/API functions can be defined inside
 signature files using ``usercode`` and ``pymethoddef`` statements
 (they must be used inside the ``python module`` block). For
 example, the following signature file ``spam.pyf``
 
-.. include:: spam.pyf
+.. include:: ./code/spam.pyf
    :literal:
 
 wraps the C library function ``system()``::
 
   f2py -c spam.pyf
 
-In Python:
+In Python this can then be used as:
 
-.. include:: spam_session.dat
-   :literal:
-
-Modifying the dictionary of a F2PY generated module
-===================================================
+.. literalinclude:: ./code/results/spam_session.dat
+   :language: python
 
-The following example illustrates how to add user-defined
-variables to a F2PY generated extension module. Given the following
-signature file
+Adding user-defined variables
+==============================
 
-.. include:: var.pyf
-  :literal:
+The following example illustrates how to add user-defined variables to a F2PY
+generated extension module by modifying the dictionary of a F2PY generated
+module. Consider the following signature file (compiled with ``f2py -c var.pyf``):
 
-compile it as ``f2py -c var.pyf``.
+.. literalinclude:: ./code/var.pyf
+  :language: fortran
 
 Notice that the second ``usercode`` statement must be defined inside
-an ``interface`` block and where the module dictionary is available through
-the variable ``d`` (see ``f2py var.pyf``-generated ``varmodule.c`` for
+an ``interface`` block and the module dictionary is available through
+the variable ``d`` (see ``varmodule.c`` generated by ``f2py var.pyf`` for
 additional details).
 
-In Python:
+Usage in Python:
 
-.. include:: var_session.dat
-  :literal:
+.. literalinclude:: ./code/results/var_session.dat
+  :language: python
 
 
 Dealing with KIND specifiers
@@ -70,7 +68,7 @@ Use the ``--f2cmap`` command-line option to pass the file name to F2PY.
 By default, F2PY assumes file name is ``.f2py_f2cmap`` in the current
 working directory.
 
-Or more generally, the f2cmap file must contain a dictionary
+More generally, the f2cmap file must contain a dictionary
 with items::
 
     <Fortran typespec> : {<selector_expr>:<C type>}
@@ -79,7 +77,7 @@ that defines mapping between Fortran type::
 
     <Fortran typespec>([kind=]<selector_expr>)
 
-and the corresponding <C type>. <C type> can be one of the following::
+and the corresponding <C type>. The <C type> can be one of the following::
 
     char
     signed_char
@@ -94,4 +92,4 @@ and the corresponding <C type>. <C type> can be one of the following::
     complex_long_double
     string
 
-For more information, see F2Py source code ``numpy/f2py/capi_maps.py``.
+For more information, see the F2Py source code ``numpy/f2py/capi_maps.py``.
diff --git a/doc/source/f2py/allocarr.f90 b/doc/source/f2py/code/allocarr.f90
index e0d6c2ec8..e0d6c2ec8 100644
--- a/doc/source/f2py/allocarr.f90
+++ b/doc/source/f2py/code/allocarr.f90
diff --git a/doc/source/f2py/array.f b/doc/source/f2py/code/array.f
index ef20c9c20..ef20c9c20 100644
--- a/doc/source/f2py/array.f
+++ b/doc/source/f2py/code/array.f
diff --git a/doc/source/f2py/calculate.f b/doc/source/f2py/code/calculate.f
index 4ff570d28..4ff570d28 100644
--- a/doc/source/f2py/calculate.f
+++ b/doc/source/f2py/code/calculate.f
diff --git a/doc/source/f2py/callback.f b/doc/source/f2py/code/callback.f
index d5cfc7574..d5cfc7574 100644
--- a/doc/source/f2py/callback.f
+++ b/doc/source/f2py/code/callback.f
diff --git a/doc/source/f2py/callback2.pyf b/doc/source/f2py/code/callback2.pyf
index 3d77eed24..3d77eed24 100644
--- a/doc/source/f2py/callback2.pyf
+++ b/doc/source/f2py/code/callback2.pyf
diff --git a/doc/source/f2py/common.f b/doc/source/f2py/code/common.f
index b098ab20c..b098ab20c 100644
--- a/doc/source/f2py/common.f
+++ b/doc/source/f2py/code/common.f
diff --git a/doc/source/f2py/extcallback.f b/doc/source/f2py/code/extcallback.f
index 9a800628e..9a800628e 100644
--- a/doc/source/f2py/extcallback.f
+++ b/doc/source/f2py/code/extcallback.f
diff --git a/doc/source/f2py/fib1.f b/doc/source/f2py/code/fib1.f
index cfbb1eea0..cfbb1eea0 100644
--- a/doc/source/f2py/fib1.f
+++ b/doc/source/f2py/code/fib1.f
diff --git a/doc/source/f2py/fib1.pyf b/doc/source/f2py/code/fib1.pyf
index 3d6cc0a54..3d6cc0a54 100644
--- a/doc/source/f2py/fib1.pyf
+++ b/doc/source/f2py/code/fib1.pyf
diff --git a/doc/source/f2py/fib2.pyf b/doc/source/f2py/code/fib2.pyf
index 4a5ae29f1..4a5ae29f1 100644
--- a/doc/source/f2py/fib2.pyf
+++ b/doc/source/f2py/code/fib2.pyf
diff --git a/doc/source/f2py/fib3.f b/doc/source/f2py/code/fib3.f
index 08b050cd2..08b050cd2 100644
--- a/doc/source/f2py/fib3.f
+++ b/doc/source/f2py/code/fib3.f
diff --git a/doc/source/f2py/ftype.f b/doc/source/f2py/code/ftype.f
index cabbb9e2d..cabbb9e2d 100644
--- a/doc/source/f2py/ftype.f
+++ b/doc/source/f2py/code/ftype.f
diff --git a/doc/source/f2py/moddata.f90 b/doc/source/f2py/code/moddata.f90
index 0e98f0467..0e98f0467 100644
--- a/doc/source/f2py/moddata.f90
+++ b/doc/source/f2py/code/moddata.f90
diff --git a/doc/source/f2py/allocarr_session.dat b/doc/source/f2py/code/results/allocarr_session.dat
index ba168c22a..ba168c22a 100644
--- a/doc/source/f2py/allocarr_session.dat
+++ b/doc/source/f2py/code/results/allocarr_session.dat
diff --git a/doc/source/f2py/array_session.dat b/doc/source/f2py/code/results/array_session.dat
index 714c03651..714c03651 100644
--- a/doc/source/f2py/array_session.dat
+++ b/doc/source/f2py/code/results/array_session.dat
diff --git a/doc/source/f2py/calculate_session.dat b/doc/source/f2py/code/results/calculate_session.dat
index c4c380700..c4c380700 100644
--- a/doc/source/f2py/calculate_session.dat
+++ b/doc/source/f2py/code/results/calculate_session.dat
diff --git a/doc/source/f2py/callback_session.dat b/doc/source/f2py/code/results/callback_session.dat
index 460c9ce28..460c9ce28 100644
--- a/doc/source/f2py/callback_session.dat
+++ b/doc/source/f2py/code/results/callback_session.dat
diff --git a/doc/source/f2py/common_session.dat b/doc/source/f2py/code/results/common_session.dat
index 2595bfbd5..2595bfbd5 100644
--- a/doc/source/f2py/common_session.dat
+++ b/doc/source/f2py/code/results/common_session.dat
diff --git a/doc/source/f2py/compile_session.dat b/doc/source/f2py/code/results/compile_session.dat
index 5c42742be..5c42742be 100644
--- a/doc/source/f2py/compile_session.dat
+++ b/doc/source/f2py/code/results/compile_session.dat
diff --git a/doc/source/f2py/extcallback_session.dat b/doc/source/f2py/code/results/extcallback_session.dat
index 5b97ab7cf..5b97ab7cf 100644
--- a/doc/source/f2py/extcallback_session.dat
+++ b/doc/source/f2py/code/results/extcallback_session.dat
diff --git a/doc/source/f2py/ftype_session.dat b/doc/source/f2py/code/results/ftype_session.dat
index e39cc128d..e39cc128d 100644
--- a/doc/source/f2py/ftype_session.dat
+++ b/doc/source/f2py/code/results/ftype_session.dat
diff --git a/doc/source/f2py/moddata_session.dat b/doc/source/f2py/code/results/moddata_session.dat
index 824bd86fc..824bd86fc 100644
--- a/doc/source/f2py/moddata_session.dat
+++ b/doc/source/f2py/code/results/moddata_session.dat
diff --git a/doc/source/f2py/run_main_session.dat b/doc/source/f2py/code/results/run_main_session.dat
index be6cacd22..be6cacd22 100644
--- a/doc/source/f2py/run_main_session.dat
+++ b/doc/source/f2py/code/results/run_main_session.dat
diff --git a/doc/source/f2py/scalar_session.dat b/doc/source/f2py/code/results/scalar_session.dat
index 3bb45ed68..3bb45ed68 100644
--- a/doc/source/f2py/scalar_session.dat
+++ b/doc/source/f2py/code/results/scalar_session.dat
diff --git a/doc/source/f2py/spam_session.dat b/doc/source/f2py/code/results/spam_session.dat
index bd5832d88..bd5832d88 100644
--- a/doc/source/f2py/spam_session.dat
+++ b/doc/source/f2py/code/results/spam_session.dat
diff --git a/doc/source/f2py/string_session.dat b/doc/source/f2py/code/results/string_session.dat
index e8f7854d9..e8f7854d9 100644
--- a/doc/source/f2py/string_session.dat
+++ b/doc/source/f2py/code/results/string_session.dat
diff --git a/doc/source/f2py/var_session.dat b/doc/source/f2py/code/results/var_session.dat
index fb0f798bf..fb0f798bf 100644
--- a/doc/source/f2py/var_session.dat
+++ b/doc/source/f2py/code/results/var_session.dat
diff --git a/doc/source/f2py/scalar.f b/doc/source/f2py/code/scalar.f
index c22f639ed..c22f639ed 100644
--- a/doc/source/f2py/scalar.f
+++ b/doc/source/f2py/code/scalar.f
diff --git a/doc/source/f2py/setup_example.py b/doc/source/f2py/code/setup_example.py
index 479acc004..479acc004 100644
--- a/doc/source/f2py/setup_example.py
+++ b/doc/source/f2py/code/setup_example.py
diff --git a/doc/source/f2py/spam.pyf b/doc/source/f2py/code/spam.pyf
index 21ea18b77..21ea18b77 100644
--- a/doc/source/f2py/spam.pyf
+++ b/doc/source/f2py/code/spam.pyf
diff --git a/doc/source/f2py/string.f b/doc/source/f2py/code/string.f
index 9246f02e7..9246f02e7 100644
--- a/doc/source/f2py/string.f
+++ b/doc/source/f2py/code/string.f
diff --git a/doc/source/f2py/var.pyf b/doc/source/f2py/code/var.pyf
index 8275ff3af..8275ff3af 100644
--- a/doc/source/f2py/var.pyf
+++ b/doc/source/f2py/code/var.pyf
diff --git a/doc/source/f2py/distutils.rst b/doc/source/f2py/distutils.rst
index 4cf30045e..575dacdff 100644
--- a/doc/source/f2py/distutils.rst
+++ b/doc/source/f2py/distutils.rst
@@ -4,16 +4,17 @@ Using via `numpy.distutils`
 
 .. currentmodule:: numpy.distutils.core
 
-:mod:`numpy.distutils` is part of NumPy extending standard Python ``distutils``
-to deal with Fortran sources and F2PY signature files, e.g. compile Fortran
-sources, call F2PY to construct extension modules, etc.
+:mod:`numpy.distutils` is part of NumPy, and extends the standard Python
+``distutils`` module to deal with Fortran sources and F2PY signature files, e.g.
+compile Fortran sources, call F2PY to construct extension modules, etc.
 
 .. topic:: Example
 
-  Consider the following `setup file`__:
+  Consider the following `setup file`__ for the ``fib`` examples in the previous
+  section:
 
-  .. include:: setup_example.py
-    :literal:
+  .. literalinclude:: ./code/setup_example.py
+    :language: python
 
   Running
 
@@ -26,30 +27,32 @@ sources, call F2PY to construct extension modules, etc.
 
   __ setup_example.py
 
+Extensions to ``distutils``
+===========================
+
 :mod:`numpy.distutils` extends ``distutils`` with the following features:
 
 * :class:`Extension` class argument ``sources`` may contain Fortran source
   files. In addition, the list ``sources`` may contain at most one
-  F2PY signature file, and then the name of an Extension module must
-  match with the ``<modulename>`` used in signature file.  It is
+  F2PY signature file, and in this case, the name of an Extension module must
+  match with the ``<modulename>`` used in signature file. It is
   assumed that an F2PY signature file contains exactly one ``python
   module`` block.
 
-  If ``sources`` does not contain a signature files, then F2PY is used
-  to scan Fortran source files for routine signatures to construct the
-  wrappers to Fortran codes.
+  If ``sources`` do not contain a signature file, then F2PY is used to scan
+  Fortran source files to construct wrappers to the Fortran codes.
 
-  Additional options to F2PY process can be given using :class:`Extension`
-  class argument ``f2py_options``.
+  Additional options to the F2PY executable can be given using the
+  :class:`Extension` class argument ``f2py_options``.
 
 * The following new ``distutils`` commands are defined:
 
   ``build_src``
     to construct Fortran wrapper extension modules, among many other things.
   ``config_fc``
-    to change Fortran compiler options
+    to change Fortran compiler options.
 
-  as well as ``build_ext`` and  ``build_clib`` commands are enhanced
+  Additionally, the ``build_ext`` and ``build_clib`` commands are also enhanced
   to support Fortran sources.
 
   Run
@@ -60,15 +63,15 @@ sources, call F2PY to construct extension modules, etc.
 
   to see available options for these commands.
 
-* When building Python packages containing Fortran sources, then one
-  can choose different Fortran compilers by using ``build_ext``
+* When building Python packages containing Fortran sources, one
+  can choose different Fortran compilers by using the ``build_ext``
   command option ``--fcompiler=<Vendor>``. Here ``<Vendor>`` can be one of the
-  following names::
+  following names (on ``linux`` systems)::
 
-    absoft sun mips intel intelv intele intelev nag compaq compaqv gnu vast pg hpux
+    absoft compaq fujitsu g95 gnu gnu95 intel intele intelem lahey nag nagfor nv pathf95 pg vast
 
-  See ``numpy_distutils/fcompiler.py`` for up-to-date list of
-  supported compilers or run
+  See ``numpy_distutils/fcompiler.py`` for an up-to-date list of
+  supported compilers for different platforms, or run
 
   ::
 
diff --git a/doc/source/f2py/f2py.getting-started.rst b/doc/source/f2py/f2py.getting-started.rst
index 27ddbb005..1709aad61 100644
--- a/doc/source/f2py/f2py.getting-started.rst
+++ b/doc/source/f2py/f2py.getting-started.rst
@@ -6,52 +6,55 @@ Wrapping Fortran or C functions to Python using F2PY consists of the
 following steps:
 
 * Creating the so-called signature file that contains descriptions of
-  wrappers to Fortran or C functions, also called as signatures of the
-  functions. In the case of Fortran routines, F2PY can create initial
+  wrappers to Fortran or C functions, also called the signatures of the
+  functions. For Fortran routines, F2PY can create an initial
   signature file by scanning Fortran source codes and
-  catching all relevant information needed to create wrapper
+  tracking all relevant information needed to create wrapper
   functions.
 
-* Optionally, F2PY created signature files can be edited to optimize
-  wrappers functions, make them "smarter" and more "Pythonic".
+  * Optionally, F2PY created signature files can be edited to optimize
+    wrapper functions, to make them "smarter" and more "Pythonic".
 
 * F2PY reads a signature file and writes a Python C/API module containing
   Fortran/C/Python bindings.
-
 * F2PY compiles all sources and builds an extension module containing
-  the wrappers. In building extension modules, F2PY uses
-  ``numpy_distutils`` that supports a number of Fortran 77/90/95
-  compilers, including Gnu, Intel,
-  Sun Fortre, SGI MIPSpro, Absoft, NAG, Compaq etc. compilers.
+  the wrappers.
+
+  * In building the extension modules, F2PY uses ``numpy_distutils`` which
+    supports a number of Fortran 77/90/95 compilers, including Gnu, Intel, Sun
+    Fortran, SGI MIPSpro, Absoft, NAG, Compaq etc.
+
+Depending on the situation, these steps can be carried out in a single composite
+command or step-by-step; in which case some steps can be omitted or combined
+with others.
 
-Depending on a particular situation, these steps can be carried out
-either by just in one command or step-by-step, some steps can be
-omitted or combined with others.
+Below, we describe three typical approaches of using F2PY. These can be read in
+order of increasing effort, but also cater to different access levels depending
+on whether the Fortran code can be freely modified.
 
-Below I'll describe three typical approaches of using F2PY.
 The following example Fortran 77 code will be used for
-illustration, save it as fib1.f:
+illustration, save it as ``fib1.f``:
 
-.. include:: fib1.f
-   :literal:
+.. literalinclude:: ./code/fib1.f
+   :language: fortran
 
 
 The quick way
 ==============
 
-The quickest way to wrap the Fortran subroutine ``FIB`` to Python is
-to run
+The quickest way to wrap the Fortran subroutine ``FIB`` for use in Python is to
+run
 
 ::
 
   python -m numpy.f2py -c fib1.f -m fib1
 
-This command builds (see ``-c`` flag, execute ``python -m numpy.f2py`` without
-arguments to see the explanation of command line options) an extension
-module ``fib1.so`` (see ``-m`` flag) to the current directory. Now, in
-Python the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
+This command compiles and wraps ``fib1.f`` (``-c``) to create the extension
+module ``fib1.so`` (``-m``) in the current directory. A list of command line
+options can be seen by executing ``python -m numpy.f2py``.  Now, in Python the
+Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
 
-  >>> import numpy
+  >>> import numpy as np
   >>> import fib1
   >>> print(fib1.fib.__doc__)
   fib(a,[n])
@@ -67,21 +70,21 @@ Python the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
   n : input int, optional
       Default: len(a)
 
-  >>> a = numpy.zeros(8, 'd')
+  >>> a = np.zeros(8, 'd')
   >>> fib1.fib(a)
   >>> print(a)
   [  0.   1.   1.   2.   3.   5.   8.  13.]
 
 .. note::
 
-  * Note that F2PY found that the second argument ``n`` is the
+  * Note that F2PY recognized that the second argument ``n`` is the
     dimension of the first array argument ``a``. Since by default all
     arguments are input-only arguments, F2PY concludes that ``n`` can
     be optional with the default value ``len(a)``.
 
   * One can use different values for optional ``n``::
 
-      >>> a1 = numpy.zeros(8, 'd')
+      >>> a1 = np.zeros(8, 'd')
       >>> fib1.fib(a1, 6)
       >>> print(a1)
       [ 0.  1.  1.  2.  3.  5.  0.  0.]
@@ -96,98 +99,94 @@ Python the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``::
       >>>
 
     F2PY implements basic compatibility checks between related
-    arguments in order to avoid any unexpected crashes.
+    arguments in order to avoid unexpected crashes.
 
-  * When a NumPy array, that is Fortran contiguous and has a dtype
-    corresponding to presumed Fortran type, is used as an input array
+  * When a NumPy array, that is Fortran contiguous and has a ``dtype``
+    corresponding to a presumed Fortran type, is used as an input array
     argument, then its C pointer is directly passed to Fortran.
 
-    Otherwise F2PY makes a contiguous copy (with a proper dtype) of
-    the input array and passes C pointer of the copy to Fortran
+    Otherwise F2PY makes a contiguous copy (with the proper ``dtype``) of
+    the input array and passes a C pointer of the copy to the Fortran
     subroutine. As a result, any possible changes to the (copy of)
     input array have no effect to the original argument, as
     demonstrated below::
 
-      >>> a = numpy.ones(8, 'i')
+      >>> a = np.ones(8, 'i')
       >>> fib1.fib(a)
       >>> print(a)
       [1 1 1 1 1 1 1 1]
 
-    Clearly, this is not an expected behaviour. The fact that the
-    above example worked with ``dtype=float`` is considered
-    accidental.
+    Clearly, this is unexpected, as Fortran typically passes by reference. That
+    the above example worked with ``dtype=float`` is considered accidental.
 
-    F2PY provides ``intent(inplace)`` attribute that would modify
+    F2PY provides an ``intent(inplace)`` attribute that modifies
     the attributes of an input array so that any changes made by
-    Fortran routine will be effective also in input argument. For example,
-    if one specifies ``intent(inplace) a`` (see below, how), then
-    the example above would read::
+    Fortran routine will be reflected in the input argument. For example,
+    if one specifies the ``intent(inplace) a`` directive (see subsequent
+    sections on how), then the example above would read::
 
-      >>> a = numpy.ones(8, 'i')
+      >>> a = np.ones(8, 'i')
       >>> fib1.fib(a)
       >>> print(a)
       [  0.   1.   1.   2.   3.   5.   8.  13.]
 
-    However, the recommended way to get changes made by Fortran
-    subroutine back to Python is to use ``intent(out)`` attribute. It
-    is more efficient and a cleaner solution.
-
-  * The usage of ``fib1.fib`` in Python is very similar to using
-    ``FIB`` in Fortran. However, using *in situ* output arguments in
-    Python indicates a poor style as there is no safety mechanism
-    in Python with respect to wrong argument types. When using Fortran
-    or C, compilers naturally discover any type mismatches during
-    compile time but in Python the types must be checked in
-    runtime. So, using *in situ* output arguments in Python may cause
-    difficult to find bugs, not to mention that the codes will be less
-    readable when all required type checks are implemented.
-
-  Though the demonstrated way of wrapping Fortran routines to Python
-  is very straightforward, it has several drawbacks (see the comments
-  above).  These drawbacks are due to the fact that there is no way
-  that F2PY can determine what is the actual intention of one or the
-  other argument, is it input or output argument, or both, or
-  something else. So, F2PY conservatively assumes that all arguments
-  are input arguments by default.
-
-  However, there are ways (see below) how to "teach" F2PY about the
-  true intentions (among other things) of function arguments; and then
-  F2PY is able to generate more Pythonic (more explicit, easier to
-  use, and less error prone) wrappers to Fortran functions.
+    However, the recommended way to have changes made by Fortran subroutine
+    propagate to Python is to use the ``intent(out)`` attribute. That approach is
+    more efficient and also cleaner.
+
+  * The usage of ``fib1.fib`` in Python is very similar to using ``FIB`` in
+    Fortran. However, using *in situ* output arguments in Python is poor style,
+    as there are no safety mechanisms in Python to protect against wrong
+    argument types. When using Fortran or C, compilers discover any type
+    mismatches during the compilation process, but in Python the types must be
+    checked at runtime. Consequently, using *in situ* output arguments in Python
+    may lead to difficult to find bugs, not to mention the fact that the
+    codes will be less readable when all required type checks are implemented.
+
+  Though the approach to wrapping Fortran routines for Python discussed so far is
+  very straightforward, it has several drawbacks (see the comments above).
+  The drawbacks are due to the fact that there is no way for F2PY to determine
+  the actual intention of the arguments; that is there is ambiguity in
+  distinguishing between input and output arguments. Consequently, F2PY assumes
+  that all arguments are input arguments by default.
+
+  However, there are ways (see below) to remove this ambiguity by "teaching"
+  F2PY about the true intentions of function arguments, and F2PY is then able to
+  generate more explicit, easier to use, and less error prone wrappers for
+  Fortran functions.
 
 The smart way
 ==============
 
-Let's apply the steps of wrapping Fortran functions to Python one by
+Let us apply the steps for wrapping Fortran functions to Python one by
 one.
 
-* First, we create a signature file from ``fib1.f`` by running
+* First, we create a signature file from ``fib1.f`` by running:
 
   ::
 
     python -m numpy.f2py fib1.f -m fib2 -h fib1.pyf
 
-  The signature file is saved to ``fib1.pyf`` (see ``-h`` flag) and
-  its contents is shown below.
+  The signature file is saved to ``fib1.pyf`` (see the ``-h`` flag) and
+  its contents are shown below.
 
-  .. include:: fib1.pyf
-     :literal:
+  .. literalinclude:: ./code/fib1.pyf
+     :language: fortran
 
-* Next, we'll teach F2PY that the argument ``n`` is an input argument
-  (use ``intent(in)`` attribute) and that the result, i.e. the
-  contents of ``a`` after calling Fortran function ``FIB``, should be
-  returned to Python (use ``intent(out)`` attribute). In addition, an
-  array ``a`` should be created dynamically using the size given by
-  the input argument ``n`` (use ``depend(n)`` attribute to indicate
-  dependence relation).
+* Next, we'll teach F2PY that the argument ``n`` is an input argument (using the
+  ``intent(in)`` attribute) and that the result, i.e., the contents of ``a``
+  after calling the Fortran function ``FIB``, should be returned to Python (using
+  the ``intent(out)`` attribute). In addition, an array ``a`` should be created
+  dynamically using the size determined by the input argument ``n`` (using the
+  ``depend(n)`` attribute to indicate this dependence relation).
 
-  The content of a modified version of ``fib1.pyf`` (saved as
+  The contents of a suitably modified version of ``fib1.pyf`` (saved as
   ``fib2.pyf``) is as follows:
 
-  .. include:: fib2.pyf
-     :literal:
+  .. literalinclude:: ./code/fib2.pyf
+     :language: fortran
 
-* And finally, we build the extension module by running
+* Finally, we build the extension module with ``numpy.distutils`` by running:
 
   ::
 
@@ -214,16 +213,14 @@ In Python::
 
 .. note::
 
-  * Clearly, the signature of ``fib2.fib`` now corresponds to the
-    intention of Fortran subroutine ``FIB`` more closely: given the
-    number ``n``, ``fib2.fib`` returns the first ``n`` Fibonacci numbers
-    as a NumPy array. Also, the new Python signature ``fib2.fib``
-    rules out any surprises that we experienced with ``fib1.fib``.
+  * The signature of ``fib2.fib`` now more closely corresponds to the
+    intention of Fortran subroutine ``FIB``: given the number ``n``,
+    ``fib2.fib`` returns the first ``n`` Fibonacci numbers as a NumPy array.
+    The new Python signature ``fib2.fib`` also rules out the unexpected behaviour in ``fib1.fib``.
 
-  * Note that by default using single ``intent(out)`` also implies
+  * Note that by default, using a single ``intent(out)`` also implies
     ``intent(hide)``. Arguments that have the ``intent(hide)`` attribute
-    specified will not be listed in the argument list of a wrapper
-    function.
+    specified will not be listed in the argument list of a wrapper function.
 
 The quick and smart way
 ========================
@@ -233,26 +230,25 @@ suitable for wrapping (e.g. third party) Fortran codes for which
 modifications to their source codes are not desirable nor even
 possible.
 
-However, if editing Fortran codes is acceptable, then the generation
-of an intermediate signature file can be skipped in most
-cases. Namely, F2PY specific attributes can be inserted directly to
-Fortran source codes using the so-called F2PY directive. A F2PY
-directive defines special comment lines (starting with ``Cf2py``, for
-example) which are ignored by Fortran compilers but F2PY interprets
-them as normal lines.
+However, if editing Fortran codes is acceptable, then the generation of an
+intermediate signature file can be skipped in most cases. F2PY specific
+attributes can be inserted directly into Fortran source codes using F2PY
+directives. A F2PY directive consists of special comment lines (starting with
+``Cf2py`` or ``!f2py``, for example) which are ignored by Fortran compilers but
+interpreted by F2PY as normal lines.
 
-Here is shown a modified version of the previous Fortran code, save it
-as ``fib3.f``:
+Consider a modified version of the previous Fortran code with F2PY directives,
+saved as ``fib3.f``:
 
-.. include:: fib3.f
-   :literal:
+.. literalinclude:: ./code/fib3.f
+   :language: fortran
 
 Building the extension module can be now carried out in one command::
 
   python -m numpy.f2py -c -m fib3 fib3.f
 
-Notice that the resulting wrapper to ``FIB`` is as "smart" as in
-previous case::
+Notice that the resulting wrapper to ``FIB`` is as "smart" (unambiguous) as in
+the previous case::
 
   >>> import fib3
   >>> print(fib3.fib.__doc__)
diff --git a/doc/source/f2py/index.rst b/doc/source/f2py/index.rst
index 492139651..c774a0df6 100644
--- a/doc/source/f2py/index.rst
+++ b/doc/source/f2py/index.rst
@@ -1,8 +1,10 @@
-#####################################
-F2PY Users Guide and Reference Manual
-#####################################
+.. _f2py:
 
-The purpose of the ``F2PY`` --*Fortran to Python interface generator*--
+=====================================
+F2PY user guide and reference manual
+=====================================
+
+The purpose of the ``F2PY`` --*Fortran to Python interface generator*-- utility
 is to provide a connection between Python and Fortran
 languages.  F2PY is a part of NumPy_ (``numpy.f2py``) and also available as a
 standalone command line tool ``f2py`` when ``numpy`` is installed that
@@ -19,11 +21,11 @@ from Python.
 .. toctree::
    :maxdepth: 2
 
-   f2py.getting-started
-   signature-file
-   python-usage
    usage
+   f2py.getting-started
    distutils
+   python-usage
+   signature-file
    advanced
 
 .. _Python: https://www.python.org/
diff --git a/doc/source/f2py/python-usage.rst b/doc/source/f2py/python-usage.rst
index 65c0cec64..ef8ccd7dd 100644
--- a/doc/source/f2py/python-usage.rst
+++ b/doc/source/f2py/python-usage.rst
@@ -4,74 +4,76 @@ Using F2PY bindings in Python
 
 All wrappers for Fortran/C routines, common blocks, or for Fortran
 90 module data generated by F2PY are exposed to Python as ``fortran``
-type objects.  Routine wrappers are callable ``fortran`` type objects
+type objects. Routine wrappers are callable ``fortran`` type objects
 while wrappers to Fortran data have attributes referring to data
 objects.
 
-All ``fortran`` type objects have attribute ``_cpointer`` that contains
-CObject referring to the C pointer of the corresponding Fortran/C
-function or variable in C level. Such CObjects can be used as a
-callback argument of F2PY generated functions to bypass Python C/API
-layer of calling Python functions from Fortran or C when the
-computational part of such functions is implemented in C or Fortran
-and wrapped with F2PY (or any other tool capable of providing CObject
-of a function).
+All ``fortran`` type objects have an attribute ``_cpointer`` that contains a
+``CObject`` referring to the C pointer of the corresponding Fortran/C function
+or variable at the C level. Such ``CObjects`` can be used as a callback argument
+for F2PY generated functions to bypass the Python C/API layer for calling Python
+functions from Fortran or C when the computational aspects of such functions are
+implemented in C or Fortran and wrapped with F2PY (or any other tool capable of
+providing the ``CObject`` of a function).
 
-Consider a Fortran 77 file ``ftype.f``:
+Consider a Fortran 77 file ```ftype.f``:
 
-  .. include:: ftype.f
-     :literal:
+  .. literalinclude:: ./code/ftype.f
+     :language: fortran
 
-and build a wrapper using ``f2py -c ftype.f -m ftype``.
+and a wrapper built using ``f2py -c ftype.f -m ftype``.
 
 In Python:
 
-  .. include:: ftype_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/ftype_session.dat
+     :language: python
 
 
 Scalar arguments
 =================
 
-In general, a scalar argument of a F2PY generated wrapper function can
+In general, a scalar argument for a F2PY generated wrapper function can
 be an ordinary Python scalar (integer, float, complex number) as well as
 an arbitrary sequence object (list, tuple, array, string) of
 scalars. In the latter case, the first element of the sequence object
 is passed to Fortran routine as a scalar argument.
 
-Note that when type-casting is required and there is possible loss of
-information (e.g. when type-casting float to integer or complex to
-float), F2PY does not raise any exception. In complex to real
-type-casting only the real part of a complex number is used.
+.. note::
+
+   * When type-casting is required and there is possible loss of information via
+     narrowing e.g. when type-casting float to integer or complex to float, F2PY
+     *does not* raise an exception.
 
-``intent(inout)`` scalar arguments are assumed to be array objects in
-order to have *in situ* changes be effective. It is recommended to use
-arrays with proper type but also other types work.
+     * For complex to real type-casting only the real part of a complex number is used.
+
+   * ``intent(inout)`` scalar arguments are assumed to be array objects in
+     order to have *in situ* changes be effective. It is recommended to use
+     arrays with proper type but also other types work.
 
 Consider the following Fortran 77 code:
 
-  .. include:: scalar.f
-     :literal:
+  .. literalinclude:: ./code/scalar.f
+     :language: fortran
 
 and wrap it using ``f2py -c -m scalar scalar.f``.
 
 In Python:
 
-  .. include:: scalar_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/scalar_session.dat
+     :language: python
 
 
 String arguments
 =================
 
-F2PY generated wrapper functions accept (almost) any Python object as
-a string argument, ``str`` is applied for non-string objects.
+F2PY generated wrapper functions accept almost any Python object as
+a string argument, since ``str`` is applied for non-string objects.
 Exceptions are NumPy arrays that must have type code ``'c'`` or
 ``'1'`` when used as string arguments.
 
-A string can have arbitrary length when using it as a string argument
-to F2PY generated wrapper function. If the length is greater than
-expected, the string is truncated. If the length is smaller than
+A string can have an arbitrary length when used as a string argument
+for an F2PY generated wrapper function. If the length is greater than
+expected, the string is truncated silently. If the length is smaller than
 expected, additional memory is allocated and filled with ``\0``.
 
 Because Python strings are immutable, an ``intent(inout)`` argument
@@ -79,43 +81,43 @@ expects an array version of a string in order to have *in situ* changes be effec
 
 Consider the following Fortran 77 code:
 
-  .. include:: string.f
-     :literal:
+  .. literalinclude:: ./code/string.f
+     :language: fortran
 
 and wrap it using ``f2py -c -m mystring string.f``.
 
 Python session:
 
-  .. include:: string_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/string_session.dat
+     :language: python
 
 
 Array arguments
 ================
 
-In general, array arguments of F2PY generated wrapper functions accept
-arbitrary sequences that can be transformed to NumPy array objects.
-An exception is ``intent(inout)`` array arguments that always must be
-proper-contiguous and have proper type, otherwise an exception is
-raised. Another exception is ``intent(inplace)`` array arguments that
-attributes will be changed *in situ* if the argument has different type
-than expected (see ``intent(inplace)`` attribute for more
-information).
-
-In general, if a NumPy array is proper-contiguous and has a proper
-type then it is directly passed to wrapped Fortran/C function.
-Otherwise, an element-wise copy of an input array is made and the
-copy, being proper-contiguous and with proper type, is used as an
-array argument.
+In general, array arguments for F2PY generated wrapper functions accept
+arbitrary sequences that can be transformed to NumPy array objects. There are
+two notable exceptions:
+
+* ``intent(inout)`` array arguments must always be proper-contiguous (defined below) and have a
+  compatible ``dtype``, otherwise an exception is raised.
+* ``intent(inplace)`` array arguments  will be changed *in situ* if the argument
+  has a different type than expected (see the ``intent(inplace)`` attribute for
+  more information).
+
+In general, if a NumPy array is proper-contiguous and has a proper type then it
+is directly passed to the wrapped Fortran/C function. Otherwise, an element-wise
+copy of the input array is made and the copy, being proper-contiguous and with
+proper type, is used as the array argument.
 
 There are two types of proper-contiguous NumPy arrays:
 
-* Fortran-contiguous arrays when data is stored column-wise,
-  i.e. indexing of data as stored in memory starts from the lowest
+* Fortran-contiguous arrays refer to data that is stored columnwise,
+  i.e. the indexing of data as stored in memory starts from the lowest
   dimension;
-* C-contiguous or simply contiguous arrays when data is stored
-  row-wise, i.e. indexing of data as stored in memory starts from the
-  highest dimension.
+* C-contiguous, or simply contiguous arrays, refer to data that is stored
+  rowwise, i.e. the indexing of data as stored in memory starts from the highest
+  dimension.
 
 For one-dimensional arrays these notions coincide.
 
@@ -132,30 +134,29 @@ To test whether an array is C-contiguous, use the ``.flags.c_contiguous``
 attribute of NumPy arrays.  To test for Fortran contiguity, use the
 ``.flags.f_contiguous`` attribute.
 
-Usually there is no need to worry about how the arrays are stored in
-memory and whether the wrapped functions, being either Fortran or C
-functions, assume one or another storage order. F2PY automatically
-ensures that wrapped functions get arguments with proper storage
-order; the corresponding algorithm is designed to make copies of
-arrays only when absolutely necessary. However, when dealing with very
-large multidimensional input arrays with sizes close to the size of
-the physical memory in your computer, then a care must be taken to use
-always proper-contiguous and proper type arguments.
+Usually there is no need to worry about how the arrays are stored in memory and
+whether the wrapped functions, being either Fortran or C functions, assume one
+or another storage order. F2PY automatically ensures that wrapped functions get
+arguments with the proper storage order; the underlying algorithm is designed to
+make copies of arrays only when absolutely necessary. However, when dealing with
+very large multidimensional input arrays with sizes close to the size of the
+physical memory in your computer, then care must be taken to ensure the usage of
+proper-contiguous and proper type arguments.
 
 To transform input arrays to column major storage order before passing
 them to Fortran routines, use the function ``numpy.asfortranarray(<array>)``.
 
 Consider the following Fortran 77 code:
 
-  .. include:: array.f
-     :literal:
+  .. literalinclude:: ./code/array.f
+     :language: fortran
 
 and wrap it using ``f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1``.
 
 In Python:
 
-  .. include:: array_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/array_session.dat
+     :language: python
 
 .. _Call-back arguments:
 
@@ -166,31 +167,32 @@ F2PY supports calling Python functions from Fortran or C codes.
 
 Consider the following Fortran 77 code:
 
-  .. include:: callback.f
-     :literal:
+  .. literalinclude:: ./code/callback.f
+     :language: fortran
 
 and wrap it using ``f2py -c -m callback callback.f``.
 
 In Python:
 
-  .. include:: callback_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/callback_session.dat
+     :language: python
 
 In the above example F2PY was able to guess accurately the signature
-of a call-back function. However, sometimes F2PY cannot establish the
-signature as one would wish and then the signature of a call-back
-function must be modified in the signature file manually. Namely,
-signature files may contain special modules (the names of such modules
-contain a substring ``__user__``) that collect various signatures of
-call-back functions.  Callback arguments in routine signatures have
-attribute ``external`` (see also ``intent(callback)`` attribute).  To
-relate a callback argument and its signature in ``__user__`` module
-block, use ``use`` statement as illustrated below. The same signature
-of a callback argument can be referred in different routine
+of the call-back function. However, sometimes F2PY cannot establish the
+appropriate signature; in these cases the signature of the call-back
+function must be explicitly defined in the signature file.
+
+To facilitate this, signature files may contain special modules (the names of
+these modules contain the special ``__user__`` sub-string) that defines the
+various signatures for call-back functions.  Callback arguments in routine
+signatures have the ``external`` attribute (see also the ``intent(callback)``
+attribute). To relate a callback argument with its signature in a ``__user__``
+module block, a ``use`` statement can be utilized as illustrated below. The same
+signature for a callback argument can be referred to in different routine
 signatures.
 
-We use the same Fortran 77 code as in previous example but now
-we'll pretend that F2PY was not able to guess the signatures of
+We use the same Fortran 77 code as in the previous example but now
+we will pretend that F2PY was not able to guess the signatures of
 call-back arguments correctly. First, we create an initial signature
 file ``callback2.pyf`` using F2PY::
 
@@ -198,40 +200,40 @@ file ``callback2.pyf`` using F2PY::
 
 Then modify it as follows
 
-  .. include:: callback2.pyf
+  .. include:: ./code/callback2.pyf
      :literal:
 
-Finally, build the extension module using ``f2py -c callback2.pyf callback.f``.
+Finally, we build the extension module using ``f2py -c callback2.pyf callback.f``.
 
-An example Python session would be identical to the previous example
-except that argument names would differ.
+An example Python session for this snippet would be identical to the previous
+example except that the argument names would differ.
 
 Sometimes a Fortran package may require that users provide routines
 that the package will use. F2PY can construct an interface to such
-routines so that Python functions could be called from Fortran.
+routines so that Python functions can be called from Fortran.
 
-Consider the following Fortran 77 subroutine that takes an array
+Consider the following Fortran 77 subroutine that takes an array as its input
 and applies a function ``func`` to its elements.
 
-  .. include:: calculate.f
-     :literal:
+  .. literalinclude:: ./code/calculate.f
+     :language: fortran
 
-It is expected that function ``func`` has been defined
-externally. In order to use a Python function as ``func``, it must
-have an attribute ``intent(callback)`` (it must be specified before
-the ``external`` statement).
+The Fortran code expects that the function ``func`` has been defined externally.
+In order to use a Python function for ``func``, it must have an attribute
+``intent(callback)`` and, it must be specified before the ``external`` statement.
 
 Finally, build an extension module using ``f2py -c -m foo calculate.f``
 
 In Python:
 
-  .. include:: calculate_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/calculate_session.dat
+     :language: python
 
-The function is included as an argument to the python function call to
-the Fortran subroutine even though it was *not* in the Fortran subroutine argument
-list. The "external" refers to the C function generated by f2py, not the python
-function itself. The python function must be supplied to the C function.
+The function is included as an argument to the python function call to the
+Fortran subroutine even though it was *not* in the Fortran subroutine argument
+list. The "external" keyword refers to the C function generated by f2py, not the
+python function itself. The python function is essentially being supplied to the
+C function.
 
 The callback function may also be explicitly set in the module.
 Then it is not necessary to pass the function in the argument list to
@@ -240,24 +242,24 @@ the python callback function is itself called by another Fortran function.
 
 Consider the following Fortran 77 subroutine:
 
-  .. include:: extcallback.f
-     :literal:
+  .. literalinclude:: ./code/extcallback.f
+     :language: fortran
 
 and wrap it using ``f2py -c -m pfromf extcallback.f``.
 
 In Python:
 
-  .. include:: extcallback_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/extcallback_session.dat
+     :language: python
 
 Resolving arguments to call-back functions
-------------------------------------------
+===========================================
 
-F2PY generated interface is very flexible with respect to call-back
+F2PY generated interfaces are very flexible with respect to call-back
 arguments.  For each call-back argument an additional optional
 argument ``<name>_extra_args`` is introduced by F2PY. This argument
 can be used to pass extra arguments to user provided call-back
-arguments.
+functions.
 
 If a F2PY generated wrapper function expects the following call-back
 argument::
@@ -281,7 +283,7 @@ is provided by a user, and in addition,
   fun_extra_args = (e_1,...,e_p)
 
 is used, then the following rules are applied when a Fortran or C
-function calls the call-back argument ``gun``:
+function evaluates the call-back argument ``gun``:
 
 * If ``p == 0`` then ``gun(a_1, ..., a_q)`` is called, here
   ``q = min(m, n)``.
@@ -292,8 +294,8 @@ function calls the call-back argument ``gun``:
 * If ``n + p`` is less than the number of required arguments to ``gun``
   then an exception is raised.
 
-The function ``gun`` may return any number of objects as a tuple. Then
-following rules are applied:
+If the function ``gun`` may return any number of objects as a tuple; then
+the following rules are applied:
 
 * If ``k < l``, then ``y_{k + 1}, ..., y_l`` are ignored.
 * If ``k > l``, then only ``x_1, ..., x_l`` are set.
@@ -303,62 +305,62 @@ Common blocks
 ==============
 
 F2PY generates wrappers to ``common`` blocks defined in a routine
-signature block. Common blocks are visible by all Fortran codes linked
-with the current extension module, but not to other extension modules
-(this restriction is due to how Python imports shared libraries).  In
+signature block. Common blocks are visible to all Fortran codes linked
+to the current extension module, but not to other extension modules
+(this restriction is due to the way Python imports shared libraries).  In
 Python, the F2PY wrappers to ``common`` blocks are ``fortran`` type
-objects that have (dynamic) attributes related to data members of
-common blocks. When accessed, these attributes return as NumPy array
-objects (multidimensional arrays are Fortran-contiguous) that
+objects that have (dynamic) attributes related to the data members of
+the common blocks. When accessed, these attributes return as NumPy array
+objects (multidimensional arrays are Fortran-contiguous) which
 directly link to data members in common blocks. Data members can be
 changed by direct assignment or by in-place changes to the
 corresponding array objects.
 
 Consider the following Fortran 77 code:
 
-  .. include:: common.f
-     :literal:
+  .. literalinclude:: ./code/common.f
+     :language: fortran
 
 and wrap it using ``f2py -c -m common common.f``.
 
 In Python:
 
-  .. include:: common_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/common_session.dat
+     :language: python
 
 
 Fortran 90 module data
 =======================
 
-The F2PY interface to Fortran 90 module data is similar to Fortran 77
+The F2PY interface to Fortran 90 module data is similar to the handling of Fortran 77
 common blocks.
 
 Consider the following Fortran 90 code:
 
-  .. include:: moddata.f90
-     :literal:
+  .. literalinclude:: ./code/moddata.f90
+     :language: fortran
 
 and wrap it using ``f2py -c -m moddata moddata.f90``.
 
 In Python:
 
-  .. include:: moddata_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/moddata_session.dat
+     :language: python
 
 
 Allocatable arrays
--------------------
+===================
 
 F2PY has basic support for Fortran 90 module allocatable arrays.
 
 Consider the following Fortran 90 code:
 
-  .. include:: allocarr.f90
-     :literal:
+  .. literalinclude:: ./code/allocarr.f90
+     :language: fortran
 
 and wrap it using ``f2py -c -m allocarr allocarr.f90``.
 
 In Python:
 
-  .. include:: allocarr_session.dat
-     :literal:
+  .. literalinclude:: ./code/results/allocarr_session.dat
+     :language: python
diff --git a/doc/source/f2py/signature-file.rst b/doc/source/f2py/signature-file.rst
index 3a163ee23..b80b31509 100644
--- a/doc/source/f2py/signature-file.rst
+++ b/doc/source/f2py/signature-file.rst
@@ -2,23 +2,22 @@
  Signature file
 ==================
 
-The syntax specification for signature files (.pyf files) is borrowed
-from the Fortran 90/95 language specification. Almost all Fortran
-90/95 standard constructs are understood, both in free and fixed
-format (recall that Fortran 77 is a subset of Fortran 90/95). F2PY
-introduces also some extensions to Fortran 90/95 language
-specification that help designing Fortran to Python interface, make it
-more "Pythonic".
-
-Signature files may contain arbitrary Fortran code (so that Fortran
-codes can be considered as signature files). F2PY silently ignores
+The syntax specification for signature files (.pyf files) is modeled on the
+Fortran 90/95 language specification. Almost all Fortran 90/95 standard
+constructs are understood, both in free and fixed format (recall that Fortran 77
+is a subset of Fortran 90/95). F2PY introduces some extensions to the Fortran
+90/95 language specification that help in the design of the Fortran to Python
+interface, making it more "Pythonic".
+
+Signature files may contain arbitrary Fortran code so that any Fortran 90/95
+codes can be treated as signature files. F2PY silently ignores
 Fortran constructs that are irrelevant for creating the interface.
-However, this includes also syntax errors. So, be careful not making
-ones ;-).
+However, this also means that syntax errors are not caught by F2PY and will only
+be caught when the library is built.
 
-In general, the contents of signature files is case-sensitive.  When
-scanning Fortran codes and writing a signature file, F2PY lowers all
-cases automatically except in multiline blocks or when ``--no-lower``
+In general, the contents of the signature files are case-sensitive. When
+scanning Fortran codes to generate a signature file, F2PY lowers all
+cases automatically except in multi-line blocks or when the ``--no-lower``
 option is used.
 
 The syntax of signature files is presented below.
@@ -27,13 +26,15 @@ Python module block
 =====================
 
 A signature file may contain one (recommended) or more ``python
-module`` blocks.  ``python module`` block describes the contents of
+module`` blocks. The ``python module`` block describes the contents of
 a Python/C extension module ``<modulename>module.c`` that F2PY
 generates.
 
-Exception: if ``<modulename>`` contains a substring ``__user__``, then
-the corresponding ``python module`` block describes the signatures of
-so-called call-back functions (see :ref:`Call-back arguments`).
+.. warning::
+
+   Exception: if ``<modulename>`` contains a substring ``__user__``, then the
+   corresponding ``python module`` block describes the signatures of call-back
+   functions (see :ref:`Call-back arguments`).
 
 A ``python module`` block has the following structure::
 
@@ -56,9 +57,9 @@ A ``python module`` block has the following structure::
     ]...
   end [python module [<modulename>]]
 
-Here brackets ``[]`` indicate an optional part, dots ``...`` indicate
-one or more of a previous part. So, ``[]...`` reads zero or more of a
-previous part.
+Here brackets ``[]`` indicate an optional section, dots ``...`` indicate one or
+more of a previous section. So, ``[]...`` is to be read as zero or more of a
+previous section.
 
 
 Fortran/C routine signatures
@@ -93,7 +94,7 @@ The signature of a Fortran block data has the following structure::
   end [ block data [<block data name>] ]
 
 Type declarations
------------------
+=================
 
 The definition of the ``<argument/variable type declaration>`` part
 is
@@ -123,33 +124,36 @@ where
 
 and
 
-+ ``<attrspec>`` is a comma separated list of attributes_;
+* ``<attrspec>`` is a comma separated list of attributes_;
 
-+ ``<arrayspec>`` is a comma separated list of dimension bounds;
+* ``<arrayspec>`` is a comma separated list of dimension bounds;
 
-+ ``<init_expr>`` is a `C expression`__.
+* ``<init_expr>`` is a `C expression`__;
 
-+ ``<intlen>`` may be negative integer for ``integer`` type
+* ``<intlen>`` may be negative integer for ``integer`` type
   specifications. In such cases ``integer*<negintlen>`` represents
-  unsigned C integers.
+  unsigned C integers;
 
 __ `C expressions`_
 
 If an argument has no ``<argument type declaration>``, its type is
 determined by applying ``implicit`` rules to its name.
 
-
 Statements
-----------
+==========
+
+Attribute statements
+^^^^^^^^^^^^^^^^^^^^^
 
-Attribute statements:
-  The ``<argument/variable attribute statement>`` is
+* The ``<argument/variable attribute statement>`` is
   ``<argument/variable type declaration>`` without ``<typespec>``.
-  In addition, in an attribute statement one cannot use other
+* In addition, in an attribute statement one cannot use other
   attributes, also ``<entitydecl>`` can be only a list of names.
 
-Use statements:
-  The definition of the ``<use statement>`` part is
+Use statements
+^^^^^^^^^^^^^^^
+
+* The definition of the ``<use statement>`` part is
 
   ::
 
@@ -161,12 +165,14 @@ Use statements:
 
      <rename_list> := <local_name> => <use_name> [ , <rename_list> ]
 
-  Currently F2PY uses ``use`` statement only for linking call-back
+* Currently F2PY uses ``use`` statement only for linking call-back
   modules and ``external`` arguments (call-back functions), see
   :ref:`Call-back arguments`.
 
-Common block statements:
-  The definition of the ``<common block statement>`` part is
+Common block statements
+^^^^^^^^^^^^^^^^^^^^^^^
+
+* The definition of the ``<common block statement>`` part is
 
   ::
 
@@ -178,18 +184,19 @@ Common block statements:
 
     <shortentitydecl> := <name> [ ( <arrayspec> ) ] [ , <shortentitydecl> ]
 
-  If a ``python module`` block contains two or more ``common`` blocks
+* If a ``python module`` block contains two or more ``common`` blocks
   with the same name, the variables from the additional declarations
   are appended.  The types of variables in ``<shortentitydecl>`` are
   defined using ``<argument type declarations>``. Note that the
   corresponding ``<argument type declarations>`` may contain array
-  specifications; then you don't need to specify these in
-  ``<shortentitydecl>``.
+  specifications; then these need not be specified in ``<shortentitydecl>``.
 
-Other statements:
-  The ``<other statement>`` part refers to any other Fortran language
+Other statements
+^^^^^^^^^^^^^^^^^
+
+* The ``<other statement>`` part refers to any other Fortran language
   constructs that are not described above. F2PY ignores most of them
-  except
+  except the following:
 
   + ``call`` statements and function calls of ``external`` arguments
     (`more details`__?);
@@ -223,7 +230,7 @@ Other statements:
       Implicit rules are used to determine the type specification of
       a variable (from the first-letter of its name) if the variable
       is not defined using ``<variable type declaration>``.  Default
-      implicit rule is given by
+      implicit rules are given by:
 
       ::
 
@@ -234,153 +241,170 @@ Other statements:
 
         entry <entry name> [([<arguments>])]
 
-      F2PY generates wrappers to all entry names using the signature
+      F2PY generates wrappers for all entry names using the signature
       of the routine block.
 
-      Tip: ``entry`` statement can be used to describe the signature
-      of an arbitrary routine allowing F2PY to generate a number of
-      wrappers from only one routine block signature. There are few
-      restrictions while doing this: ``fortranname`` cannot be used,
-      ``callstatement`` and ``callprotoargument`` can be used only if
-      they are valid for all entry routines, etc.
+      .. note::
+
+        The ``entry`` statement can be used to describe the signature of an
+        arbitrary subroutine or function allowing F2PY to generate a number of
+        wrappers from only one routine block signature. There are few
+        restrictions while doing this: ``fortranname`` cannot be used,
+        ``callstatement`` and ``callprotoargument`` can be used only if they are
+        valid for all entry routines, etc.
+
+F2PY statements
+^^^^^^^^^^^^^^^^
 
   In addition, F2PY introduces the following statements:
 
-  + ``threadsafe``
-      Use ``Py_BEGIN_ALLOW_THREADS .. Py_END_ALLOW_THREADS`` block
-      around the call to Fortran/C function.
-
-  + ``callstatement <C-expr|multi-line block>``
-      Replace F2PY generated call statement to Fortran/C function with
-      ``<C-expr|multi-line block>``. The wrapped Fortran/C function
-      is available as ``(*f2py_func)``. To raise an exception, set
-      ``f2py_success = 0`` in ``<C-expr|multi-line block>``.
-
-  + ``callprotoargument <C-typespecs>``
-      When ``callstatement`` statement is used then F2PY may not
-      generate proper prototypes for Fortran/C functions (because
-      ``<C-expr>`` may contain any function calls and F2PY has no way
-      to determine what should be the proper prototype). With this
-      statement you can explicitly specify the arguments of the
-      corresponding prototype::
-
-        extern <return type> FUNC_F(<routine name>,<ROUTINE NAME>)(<callprotoargument>);
-
-  + ``fortranname [<actual Fortran/C routine name>]``
-      You can use arbitrary ``<routine name>`` for a given Fortran/C
-      function. Then you have to specify
-      ``<actual Fortran/C routine name>`` with this statement.
-
-      If ``fortranname`` statement is used without
-      ``<actual Fortran/C routine name>`` then a dummy wrapper is
-      generated.
-
-  + ``usercode <multi-line block>``
-      When used inside ``python module`` block, then given C code
-      will be inserted to generated C/API source just before
-      wrapper function definitions. Here you can define arbitrary
-      C functions to be used in initialization of optional arguments,
-      for example. If ``usercode`` is used twice inside ``python
-      module`` block then the second multiline block is inserted
-      after the definition of external routines.
-
-      When used inside ``<routine signature>``, then given C code will
-      be inserted to the corresponding wrapper function just after
-      declaring variables but before any C statements. So, ``usercode``
-      follow-up can contain both declarations and C statements.
-
-      When used inside the first ``interface`` block, then given C
-      code will be inserted at the end of the initialization
-      function of the extension module. Here you can modify extension
-      modules dictionary. For example, for defining additional
-      variables etc.
-
-  + ``pymethoddef <multiline block>``
-      Multiline block will be inserted to the definition of
-      module methods ``PyMethodDef``-array. It must be a
-      comma-separated list of C arrays (see `Extending and Embedding`__
-      Python documentation for details).
-      ``pymethoddef`` statement can be used only inside
-      ``python module`` block.
+``threadsafe``
+  Uses a ``Py_BEGIN_ALLOW_THREADS .. Py_END_ALLOW_THREADS`` block
+  around the call to Fortran/C function.
+
+``callstatement <C-expr|multi-line block>``
+  Replaces the  F2PY generated call statement to Fortran/C function with
+  ``<C-expr|multi-line block>``. The wrapped Fortran/C function is available
+  as ``(*f2py_func)``.
+
+  To raise an exception, set ``f2py_success = 0`` in ``<C-expr|multi-line
+  block>``.
+
+``callprotoargument <C-typespecs>``
+  When the ``callstatement`` statement is used then F2PY may not
+  generate proper prototypes for Fortran/C functions (because
+  ``<C-expr>`` may contain any function calls and F2PY has no way
+  to determine what should be the proper prototype).
+
+  With this statement you can explicitly specify the arguments of the
+  corresponding prototype::
+
+    extern <return type> FUNC_F(<routine name>,<ROUTINE NAME>)(<callprotoargument>);
+
+``fortranname [<actual Fortran/C routine name>]``
+  F2PY allows for the use of an arbitrary ``<routine name>`` for a given
+  Fortran/C function. Then this statement is used for the ``<actual
+  Fortran/C routine name>``.
+
+  If ``fortranname`` statement is used without
+  ``<actual Fortran/C routine name>`` then a dummy wrapper is
+  generated.
+
+``usercode <multi-line block>``
+  When this is used inside a ``python module`` block, the given C code will
+  be inserted to generated C/API source just before wrapper function
+  definitions.
+
+  Here you can define arbitrary C functions to be used for the
+  initialization of optional arguments.
+
+  For example, if ``usercode`` is used twice inside ``python module`` block
+  then the second multi-line block is inserted after the definition of
+  the external routines.
+
+  When used inside ``<routine signature>``, then the given C code will be
+  inserted into the corresponding wrapper function just after the
+  declaration of  variables but before any C statements. So, the
+  ``usercode`` follow-up can contain both declarations and C statements.
+
+  When used inside the first ``interface`` block, then the given C code will
+  be inserted at the end of the initialization function of the extension
+  module. This is how the extension modules dictionary can be modified and
+  has many use-cases; for example, to define additional variables.
+
+``pymethoddef <multiline block>``
+  This is a multi-line block which will be inserted into the definition of a
+  module methods ``PyMethodDef``-array. It must be a comma-separated list of
+  C arrays (see `Extending and Embedding`__ Python documentation for
+  details).  ``pymethoddef`` statement can be used only inside ``python
+  module`` block.
 
   __ https://docs.python.org/extending/index.html
 
 Attributes
-------------
+============
 
 The following attributes are used by F2PY:
 
 ``optional``
   The corresponding argument is moved to the end of ``<optional
   arguments>`` list. A default value for an optional argument can be
-  specified ``<init_expr>``, see ``entitydecl`` definition. Note that
-  the default value must be given as a valid C expression.
+  specified via ``<init_expr>``, see the ``entitydecl`` definition.
+
 
-  Note that whenever ``<init_expr>`` is used, ``optional`` attribute
-  is set automatically by F2PY.
+  .. note::
 
-  For an optional array argument, all its dimensions must be bounded.
+   * The default value must be given as a valid C expression.
+   * Whenever ``<init_expr>`` is used, ``optional`` attribute
+     is set automatically by F2PY.
+   * For an optional array argument, all its dimensions must be bounded.
 
 ``required``
-  The corresponding argument is considered as a required one. This is
-  default. You need to specify ``required`` only if there is a need to
-  disable automatic ``optional`` setting when ``<init_expr>`` is used.
+  The corresponding argument with this attribute considered mandatory. This is
+  the default. ``required`` should only be specified if there is a need to
+  disable the automatic ``optional`` setting when ``<init_expr>`` is used.
 
-  If Python ``None`` object is used as a required argument, the
+  If a Python ``None`` object is used as a required argument, the
   argument is treated as optional. That is, in the case of array
-  argument, the memory is allocated. And if ``<init_expr>`` is given,
-  the corresponding initialization is carried out.
+  argument, the memory is allocated. If ``<init_expr>`` is given, then the
+  corresponding initialization is carried out.
 
 ``dimension(<arrayspec>)``
-  The corresponding variable is considered as an array with given
-  dimensions in ``<arrayspec>``.
+  The corresponding variable is considered as an array with dimensions given in
+  ``<arrayspec>``.
 
 ``intent(<intentspec>)``
   This specifies the "intention" of the corresponding
   argument. ``<intentspec>`` is a comma separated list of the
   following keys:
 
-  + ``in``
-      The argument is considered as an input-only argument. It means
-      that the value of the argument is passed to Fortran/C function and
-      that function is expected not to change the value of an argument.
-
-  + ``inout``
-      The argument is considered as an input/output or *in situ*
-      output argument. ``intent(inout)`` arguments can be only
-      "contiguous" NumPy arrays with proper type and size.  Here
-      "contiguous" can be either in Fortran or C sense. The latter one
-      coincides with the contiguous concept used in NumPy and is
-      effective only if ``intent(c)`` is used. Fortran contiguity
-      is assumed by default.
-
-      Using ``intent(inout)`` is generally not recommended, use
-      ``intent(in,out)`` instead. See also ``intent(inplace)`` attribute.
-
-  + ``inplace``
-      The argument is considered as an input/output or *in situ*
-      output argument. ``intent(inplace)`` arguments must be
-      NumPy arrays with proper size. If the type of an array is
-      not "proper" or the array is non-contiguous then the array
-      will be changed in-place to fix the type and make it contiguous.
-
-      Using ``intent(inplace)`` is generally not recommended either.
-      For example, when slices have been taken from an
-      ``intent(inplace)`` argument then after in-place changes,
-      slices data pointers may point to unallocated memory area.
-
-  + ``out``
-      The argument is considered as a return variable. It is appended
-      to the ``<returned variables>`` list. Using ``intent(out)``
-      sets ``intent(hide)`` automatically, unless also
-      ``intent(in)`` or ``intent(inout)`` were used.
-
-      By default, returned multidimensional arrays are
-      Fortran-contiguous. If ``intent(c)`` is used, then returned
-      multidimensional arrays are C-contiguous.
-
-  + ``hide``
-      The argument is removed from the list of required or optional
+  * ``in``
+      The corresponding argument is considered to be input-only. This means that the value of
+      the argument is passed to a Fortran/C function and that the function is
+      expected to not change the value of this argument.
+
+  * ``inout``
+      The corresponding argument is marked for input/output or as an *in situ* output
+      argument. ``intent(inout)`` arguments can be only "contiguous" NumPy
+      arrays with proper type and size. Here "contiguous" can be either in the
+      Fortran or C sense. The latter  coincides with the default contiguous
+      concept used in NumPy and is effective only if ``intent(c)`` is used. F2PY
+      assumes Fortran contiguous arguments by default.
+
+      .. note::
+
+         Using ``intent(inout)`` is generally not recommended, use ``intent(in,out)`` instead.
+
+     See also the ``intent(inplace)`` attribute.
+
+  * ``inplace``
+      The corresponding argument is considered to be an input/output or *in situ* output
+      argument. ``intent(inplace)`` arguments must be NumPy arrays of a proper
+      size. If the type of an array is not "proper" or the array is
+      non-contiguous then the array will be modified in-place to fix the type and
+      make it contiguous.
+
+      .. note::
+
+        Using ``intent(inplace)`` is generally not recommended either.
+
+        For example, when slices have been taken from an ``intent(inplace)`` argument
+        then after in-place changes, the data pointers for the slices may point to
+        an unallocated memory area.
+
+
+  * ``out``
+      The corresponding argument is considered to be a return variable. It is appended to the
+      ``<returned variables>`` list. Using ``intent(out)`` sets ``intent(hide)``
+      automatically, unless  ``intent(in)`` or ``intent(inout)`` are specified
+      as well.
+
+      By default, returned multidimensional arrays are Fortran-contiguous. If
+      ``intent(c)`` attribute is used, then the returned multidimensional arrays
+      are C-contiguous.
+
+  * ``hide``
+      The corresponding argument is removed from the list of required or optional
       arguments. Typically ``intent(hide)`` is used with ``intent(out)``
       or when ``<init_expr>`` completely determines the value of the
       argument like in the following example::
@@ -388,18 +412,17 @@ The following attributes are used by F2PY:
         integer intent(hide),depend(a) :: n = len(a)
         real intent(in),dimension(n) :: a
 
-  + ``c``
-      The argument is treated as a C scalar or C array argument.  In
-      the case of a scalar argument, its value is passed to C function
-      as a C scalar argument (recall that Fortran scalar arguments are
-      actually C pointer arguments).  In the case of an array
-      argument, the wrapper function is assumed to treat
+  * ``c``
+      The corresponding argument is treated as a C scalar or C array argument. For the case
+      of a scalar argument, its value is passed to a C function as a C scalar
+      argument (recall that Fortran scalar arguments are actually C pointer
+      arguments).  For array arguments, the wrapper function is assumed to treat
       multidimensional arrays as C-contiguous arrays.
 
       There is no need to use ``intent(c)`` for one-dimensional
-      arrays, no matter if the wrapped function is either a Fortran or
-      a C function. This is because the concepts of Fortran- and
-      C contiguity overlap in one-dimensional cases.
+      arrays, irrespective of whether the wrapped function is in Fortran or C.
+      This is because the concepts of Fortran- and C contiguity overlap in
+      one-dimensional cases.
 
       If ``intent(c)`` is used as a statement but without an entity
       declaration list, then F2PY adds the ``intent(c)`` attribute to all
@@ -409,110 +432,121 @@ The following attributes are used by F2PY:
       attribute for ``<routine name>`` in order to disable Fortran
       specific ``F_FUNC(..,..)`` macros.
 
-  + ``cache``
-      The argument is treated as a junk of memory. No Fortran nor C
-      contiguity checks are carried out. Using ``intent(cache)``
-      makes sense only for array arguments, also in connection with
-      ``intent(hide)`` or ``optional`` attributes.
-
-  + ``copy``
-      Ensure that the original contents of ``intent(in)`` argument is
-      preserved. Typically used in connection with ``intent(in,out)``
-      attribute.  F2PY creates an optional argument
-      ``overwrite_<argument name>`` with the default value ``0``.
-
-  + ``overwrite``
-      The original contents of the ``intent(in)`` argument may be
-      altered by the Fortran/C function.  F2PY creates an optional
-      argument ``overwrite_<argument name>`` with the default value
-      ``1``.
-
-  + ``out=<new name>``
-      Replace the return name with ``<new name>`` in the ``__doc__``
-      string of a wrapper function.
-
-  + ``callback``
-      Construct an external function suitable for calling Python function
+  * ``cache``
+      The corresponding argument is treated as junk memory. No Fortran nor C contiguity
+      checks are carried out. Using ``intent(cache)`` makes sense only for array
+      arguments, also in conjunction with ``intent(hide)`` or ``optional``
+      attributes.
+
+  * ``copy``
+      Ensures that the original contents of ``intent(in)`` argument is
+      preserved. Typically used with the ``intent(in,out)`` attribute. F2PY
+      creates an optional argument ``overwrite_<argument name>`` with the
+      default value ``0``.
+
+  * ``overwrite``
+      This indicates that the original contents of the ``intent(in)`` argument
+      may be altered by the Fortran/C function.  F2PY creates an optional
+      argument ``overwrite_<argument name>`` with the default value ``1``.
+
+  * ``out=<new name>``
+      Replaces the returned name with ``<new name>`` in the ``__doc__`` string
+      of the wrapper function.
+
+  * ``callback``
+      Constructs an external function suitable for calling Python functions
       from Fortran. ``intent(callback)`` must be specified before the
-      corresponding ``external`` statement. If 'argument' is not in
-      argument list then it will be added to Python wrapper but only
-      initializing external function.
-
-      Use ``intent(callback)`` in situations where a Fortran/C code
-      assumes that a user implements a function with given prototype
-      and links it to an executable. Don't use ``intent(callback)``
-      if function appears in the argument list of a Fortran routine.
-
-      With ``intent(hide)`` or ``optional`` attributes specified and
-      using a wrapper function without specifying the callback argument
-      in argument list then call-back function is looked in the
-      namespace of F2PY generated extension module where it can be
-      set as a module attribute by a user.
-
-  + ``aux``
-      Define auxiliary C variable in F2PY generated wrapper function.
-      Useful to save parameter values so that they can be accessed
-      in initialization expression of other variables. Note that
-      ``intent(aux)`` silently implies ``intent(c)``.
+      corresponding ``external`` statement. If the 'argument' is not in
+      the argument list then it will be added to Python wrapper but only
+      by initializing an external function.
+
+      .. note::
+
+         Use ``intent(callback)`` in situations where the Fortran/C code assumes
+         that the user implemented a function with a given prototype and linked
+         it to an executable. Don't use ``intent(callback)`` if the function
+         appears in the argument list of a Fortran routine.
+
+      With ``intent(hide)`` or ``optional`` attributes specified and using a
+      wrapper function without specifying the callback argument in the argument
+      list; then the call-back function is assumed to be found in the  namespace
+      of the F2PY generated extension module where it can be set as a module
+      attribute by a user.
+
+  * ``aux``
+      Defines an auxiliary C variable in the F2PY generated wrapper function.
+      Useful to save parameter values so that they can be accessed in
+      initialization expressions for other variables.
+
+      .. note::
+
+         ``intent(aux)`` silently implies ``intent(c)``.
 
   The following rules apply:
 
-  + If no ``intent(in | inout | out | hide)`` is specified,
+  * If none of ``intent(in | inout | out | hide)`` are specified,
     ``intent(in)`` is assumed.
-  + ``intent(in,inout)`` is ``intent(in)``.
-  + ``intent(in,hide)`` or ``intent(inout,hide)`` is
-    ``intent(hide)``.
-  + ``intent(out)`` is ``intent(out,hide)`` unless ``intent(in)`` or
-    ``intent(inout)`` is specified.
-  + If ``intent(copy)`` or ``intent(overwrite)`` is used, then an
-    additional optional argument is introduced with a name
-    ``overwrite_<argument name>`` and a default value 0 or 1, respectively.
-  + ``intent(inout,inplace)`` is ``intent(inplace)``.
-  + ``intent(in,inplace)`` is ``intent(inplace)``.
-  + ``intent(hide)`` disables ``optional`` and ``required``.
+
+    * ``intent(in,inout)`` is ``intent(in)``;
+
+    * ``intent(in,hide)`` or ``intent(inout,hide)`` is ``intent(hide)``;
+
+    * ``intent(out)`` is ``intent(out,hide)`` unless ``intent(in)`` or
+      ``intent(inout)`` is specified.
+
+  * If ``intent(copy)`` or ``intent(overwrite)`` is used, then an additional
+    optional argument is introduced with a name ``overwrite_<argument name>``
+    and a default value 0 or 1, respectively.
+
+    * ``intent(inout,inplace)`` is ``intent(inplace)``;
+
+    * ``intent(in,inplace)`` is ``intent(inplace)``;
+
+    * ``intent(hide)`` disables ``optional`` and ``required``.
 
 ``check([<C-booleanexpr>])``
-  Perform consistency check of arguments by evaluating
-  ``<C-booleanexpr>``; if ``<C-booleanexpr>`` returns 0, an exception
-  is raised.
+  Performs a consistency check on the arguments by evaluating
+  ``<C-booleanexpr>``; if ``<C-booleanexpr>`` returns 0, an exception is raised.
+
+  .. note::
 
-  If ``check(..)`` is not used then F2PY generates few standard checks
-  (e.g. in a case of an array argument, check for the proper shape
-  and size) automatically. Use ``check()`` to disable checks generated
-  by F2PY.
+     If ``check(..)`` is not used then F2PY automatically generates a few
+     standard checks (e.g.  in a case of an array argument, it checks for the
+     proper shape and size). Use ``check()`` to disable checks
+     generated by F2PY.
 
 ``depend([<names>])``
   This declares that the corresponding argument depends on the values
-  of variables in the list ``<names>``. For example, ``<init_expr>``
+  of variables in the ``<names>`` list. For example, ``<init_expr>``
   may use the values of other arguments.  Using information given by
   ``depend(..)`` attributes, F2PY ensures that arguments are
-  initialized in a proper order. If ``depend(..)`` attribute is not
+  initialized in a proper order. If the ``depend(..)`` attribute is not
   used then F2PY determines dependence relations automatically. Use
-  ``depend()`` to disable dependence relations generated by F2PY.
+  ``depend()`` to disable the dependence relations generated by F2PY.
 
   When you edit dependence relations that were initially generated by
   F2PY, be careful not to break the dependence relations of other
-  relevant variables. Another thing to watch out is cyclic
+  relevant variables. Another thing to watch out for is cyclic
   dependencies. F2PY is able to detect cyclic dependencies
   when constructing wrappers and it complains if any are found.
 
 ``allocatable``
-  The corresponding variable is Fortran 90 allocatable array defined
-  as Fortran 90 module data.
+  The corresponding variable is a Fortran 90 allocatable array defined as
+  Fortran 90 module data.
 
 .. _external:
 
 ``external``
   The corresponding argument is a function provided by user. The
-  signature of this so-called call-back function can be defined
+  signature of this call-back function can be defined
 
   - in ``__user__`` module block,
   - or by demonstrative (or real, if the signature file is a real Fortran
     code) call in the ``<other statements>`` block.
 
-  For example, F2PY generates from
+  For example, F2PY generates from:
 
-  ::
+  .. code-block:: fortran
 
     external cb_sub, cb_fun
     integer n
@@ -520,7 +554,9 @@ The following attributes are used by F2PY:
     call cb_sub(a,n)
     r = cb_fun(4)
 
-  the following call-back signatures::
+  the following call-back signatures:
+
+  .. code-block:: fortran
 
     subroutine cb_sub(a,n)
         real dimension(n) :: a
@@ -531,7 +567,9 @@ The following attributes are used by F2PY:
         real :: r
     end function cb_fun
 
-  The corresponding user-provided Python function are then::
+  The corresponding user-provided Python function are then:
+
+  .. code-block:: python
 
     def cb_sub(a,[n]):
         ...
@@ -540,49 +578,50 @@ The following attributes are used by F2PY:
         ...
         return r
 
-  See also ``intent(callback)`` attribute.
+  See also the ``intent(callback)`` attribute.
 
 ``parameter``
-  The corresponding variable is a parameter and it must have a fixed
-  value. F2PY replaces all parameter occurrences by their
-  corresponding values.
+  This indicates that the corresponding variable is a parameter and it must have
+  a fixed value. F2PY replaces all parameter occurrences by their corresponding
+  values.
 
 Extensions
 ============
 
 F2PY directives
------------------
+^^^^^^^^^^^^^^^^
 
-The so-called F2PY directives allow using F2PY signature file
-constructs also in Fortran 77/90 source codes. With this feature you
-can skip (almost) completely intermediate signature file generations
-and apply F2PY directly to Fortran source codes.
+The F2PY directives allow using F2PY signature file constructs in
+Fortran 77/90 source codes. With this feature one  can (almost) completely skip
+the intermediate signature file generation and apply F2PY directly to Fortran
+source codes.
 
-F2PY directive has the following form::
+F2PY directives have the following form::
 
   <comment char>f2py ...
 
 where allowed comment characters for fixed and free format Fortran
 codes are ``cC*!#`` and ``!``, respectively. Everything that follows
 ``<comment char>f2py`` is ignored by a compiler but read by F2PY as a
-normal Fortran, non-comment line:
+normal non-comment  Fortran line:
 
+.. note::
   When F2PY finds a line with F2PY directive, the directive is first
   replaced by 5 spaces and then the line is reread.
 
 For fixed format Fortran codes, ``<comment char>`` must be at the
 first column of a file, of course. For free format Fortran codes,
-F2PY directives can appear anywhere in a file.
+the F2PY directives can appear anywhere in a file.
 
 C expressions
---------------
+^^^^^^^^^^^^^^
 
 C expressions are used in the following parts of signature files:
 
-* ``<init_expr>`` of variable initialization;
+* ``<init_expr>`` for variable initialization;
 * ``<C-booleanexpr>`` of the ``check`` attribute;
-* ``<arrayspec> of the ``dimension`` attribute;
-* ``callstatement`` statement, here also a C multiline block can be used.
+* ``<arrayspec>`` of the ``dimension`` attribute;
+* ``callstatement`` statement, here also a C multi-line block can be used.
 
 A C expression may contain:
 
@@ -592,15 +631,19 @@ A C expression may contain:
   according to given dependence relations;
 * the following CPP macros:
 
-  ``rank(<name>)``
+  * ``rank(<name>)``
     Returns the rank of an array ``<name>``.
-  ``shape(<name>,<n>)``
+
+  * ``shape(<name>,<n>)``
     Returns the ``<n>``-th dimension of an array ``<name>``.
-  ``len(<name>)``
+
+  * ``len(<name>)``
     Returns the length of an array ``<name>``.
-  ``size(<name>)``
+
+  * ``size(<name>)``
     Returns the size of an array ``<name>``.
-  ``slen(<name>)``
+
+  * ``slen(<name>)``
     Returns the length of a string ``<name>``.
 
 For initializing an array ``<array name>``, F2PY generates a loop over
@@ -615,7 +658,7 @@ from ``0`` to ``shape(<array name>,<i>)-1``.
 For example, a function ``myrange(n)`` generated from the following
 signature
 
-::
+.. code-block::
 
        subroutine myrange(a,n)
          fortranname        ! myrange is a dummy wrapper
@@ -630,23 +673,23 @@ is equivalent to ``numpy.arange(n,dtype=float)``.
   F2PY may lower cases also in C expressions when scanning Fortran codes
   (see ``--[no]-lower`` option).
 
-Multiline blocks
-------------------
+Multi-line blocks
+^^^^^^^^^^^^^^^^^^
 
-A multiline block starts with ``'''`` (triple single-quotes) and ends
-with ``'''`` in some *strictly* subsequent line.  Multiline blocks can
-be used only within .pyf files. The contents of a multiline block can
+A multi-line block starts with ``'''`` (triple single-quotes) and ends
+with ``'''`` in some *strictly* subsequent line.  Multi-line blocks can
+be used only within .pyf files. The contents of a multi-line block can
 be arbitrary (except that it cannot contain ``'''``) and no
 transformations (e.g. lowering cases) are applied to it.
 
-Currently, multiline blocks can be used in the following constructs:
+Currently, multi-line blocks can be used in the following constructs:
 
-+ as a C expression of the ``callstatement`` statement;
+* as a C expression of the ``callstatement`` statement;
 
-+ as a C type specification of the ``callprotoargument`` statement;
+* as a C type specification of the ``callprotoargument`` statement;
 
-+ as a C code block of the ``usercode`` statement;
+* as a C code block of the ``usercode`` statement;
 
-+ as a list of C arrays of the ``pymethoddef`` statement;
+* as a list of C arrays of the ``pymethoddef`` statement;
 
-+ as documentation string.
+* as a documentation string.
diff --git a/doc/source/f2py/usage.rst b/doc/source/f2py/usage.rst
index 6c3b4b6ef..596148799 100644
--- a/doc/source/f2py/usage.rst
+++ b/doc/source/f2py/usage.rst
@@ -3,9 +3,9 @@ Using F2PY
 ===========
 
 F2PY can be used either as a command line tool ``f2py`` or as a Python
-module ``numpy.f2py``. While we try to install the command line tool as part
+module ``numpy.f2py``. While we try to provide the command line tool as part
 of the numpy setup, some platforms like Windows make it difficult to
-reliably put the executable on the ``PATH``. We will refer to ``f2py``
+reliably put the executables on the ``PATH``. We will refer to ``f2py``
 in this document but you may have to run it as a module::
 
    python -m numpy.f2py
@@ -21,32 +21,40 @@ Command ``f2py``
 When used as a command line tool, ``f2py`` has three major modes,
 distinguished by the usage of ``-c`` and ``-h`` switches:
 
+Signature file generation
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 1. To scan Fortran sources and generate a signature file, use
 
-   ::
+   .. code-block:: sh
 
      f2py -h <filename.pyf> <options> <fortran files>   \
        [[ only: <fortran functions>  : ]                \
         [ skip: <fortran functions>  : ]]...            \
        [<fortran files> ...]
 
-   Note that a Fortran source file can contain many routines, and not
-   necessarily all routines are needed to be used from Python. So, you
-   can either specify which routines should be wrapped (in ``only: .. :``
-   part) or which routines F2PY should ignored (in ``skip: .. :`` part).
+   .. note::
+
+    A Fortran source file can contain many routines, and it is often
+    not necessary to allow all routines be usable from Python. In such cases,
+    either specify which routines should be wrapped (in the ``only: .. :`` part)
+    or which routines F2PY should ignored (in the ``skip: .. :`` part).
 
    If ``<filename.pyf>`` is specified as ``stdout`` then signatures
-   are send to standard output instead of a file.
+   are written to standard output instead of a file.
 
-   Among other options (see below), the following options can be used
+   Among other options (see below), the following can be used
    in this mode:
 
    ``--overwrite-signature``
-     Overwrite existing signature file.
+     Overwrites an existing signature file.
+
+Extension module construction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 2. To construct an extension module, use
 
-   ::
+   .. code-block:: sh
 
      f2py -m <modulename> <options> <fortran files>   \
        [[ only: <fortran functions>  : ]              \
@@ -61,17 +69,19 @@ distinguished by the usage of ``-c`` and ``-h`` switches:
    in this mode:
 
    ``--debug-capi``
-     Add debugging hooks to the extension module. When using this
-     extension module, various information about the wrapper is printed
-     to standard output, for example, the values of variables, the
-     steps taken, etc.
+     Adds debugging hooks to the extension module. When using this extension
+     module, various diagnostic information about the wrapper is written to
+     the standard output, for example, the values of variables, the steps taken,
+     etc.
 
    ``-include'<includefile>'``
      Add a CPP ``#include`` statement to the extension module source.
-     ``<includefile>`` should be given in one of the following forms::
+     ``<includefile>`` should be given in one of the following forms
 
-       "filename.ext"
-       <filename.ext>
+       .. code-block:: cpp
+
+        "filename.ext"
+        <filename.ext>
 
      The include statement is inserted just before the wrapper
      functions. This feature enables using arbitrary C functions
@@ -91,16 +101,19 @@ distinguished by the usage of ``-c`` and ``-h`` switches:
      List system resources found by ``numpy_distutils/system_info.py``.
      For example, try ``f2py --help-link lapack_opt``.
 
+Building a module
+^^^^^^^^^^^^^^^^^
+
 3. To build an extension module, use
 
-   ::
+   .. code-block:: sh
 
      f2py -c <options> <fortran files>       \
        [[ only: <fortran functions>  : ]     \
         [ skip: <fortran functions>  : ]]... \
        [ <fortran/c source files> ] [ <.o, .a, .so files> ]
  
-   If ``<fortran files>`` contains a signature file, then a source for
+   If ``<fortran files>`` contains a signature file, then the source for
    an extension module is constructed, all Fortran and C sources are
    compiled, and finally all object and library files are linked to the
    extension module ``<modulename>.so`` which is saved into the current
@@ -108,26 +121,25 @@ distinguished by the usage of ``-c`` and ``-h`` switches:
 
    If ``<fortran files>`` does not contain a signature file, then an
    extension module is constructed by scanning all Fortran source codes
-   for routine signatures.
+   for routine signatures, before proceeding to build the extension module.
  
-   Among other options (see below) and options described in previous
-   mode, the following options can be used in this mode:
+   Among other options (see below) and options described for previous
+   modes, the following options can be used in this mode:
  
    ``--help-fcompiler``
-     List available Fortran compilers.
-   ``--help-compiler`` [depreciated]
-     List available Fortran compilers.
+     List the available Fortran compilers.
+   ``--help-compiler`` **[depreciated]**
+     List the available Fortran compilers.
    ``--fcompiler=<Vendor>``
-     Specify Fortran compiler type by vendor.
+     Specify a Fortran compiler type by vendor.
    ``--f77exec=<path>``
-     Specify the path to F77 compiler
-   ``--fcompiler-exec=<path>`` [depreciated]
-     Specify the path to F77 compiler
+     Specify the path to a F77 compiler
+   ``--fcompiler-exec=<path>`` **[depreciated]**
+     Specify the path to a F77 compiler
    ``--f90exec=<path>``
-     Specify the path to F90 compiler
-   ``--f90compiler-exec=<path>`` [depreciated]
-     Specify the path to F90 compiler
- 
+     Specify the path to a F90 compiler
+   ``--f90compiler-exec=<path>`` **[depreciated]**
+     Specify the path to a F90 compiler
    ``--f77flags=<string>``
      Specify F77 compiler flags
    ``--f90flags=<string>``
@@ -137,12 +149,11 @@ distinguished by the usage of ``-c`` and ``-h`` switches:
    ``--arch=<string>``
      Specify architecture specific optimization flags
    ``--noopt``
-     Compile without optimization
+     Compile without optimization flags
    ``--noarch``
-     Compile without arch-dependent optimization
+     Compile without arch-dependent optimization flags
    ``--debug``
      Compile with debugging information
- 
    ``-l<libname>``
      Use the library ``<libname>`` when linking.
    ``-D<macro>[=<defn=1>]``
@@ -155,34 +166,35 @@ distinguished by the usage of ``-c`` and ``-h`` switches:
    ``-L<dir>``
      Add directory ``<dir>`` to the list of directories to  be  searched
      for ``-l``.
- 
    ``link-<resource>``
-     Link extension module with <resource> as defined by
+     Link the extension module with <resource> as defined by
      ``numpy_distutils/system_info.py``. E.g. to link with optimized
      LAPACK libraries (vecLib on MacOSX, ATLAS elsewhere), use
      ``--link-lapack_opt``. See also ``--help-link`` switch.
 
    .. note:: The ``f2py -c`` option must be applied either to an existing ``.pyf`` file (plus the source/object/library files) or one must specify the ``-m <modulename>`` option (plus the sources/object/library files). Use one of the following options:
 
-      ::
+   .. code-block:: sh
 
          f2py -c -m fib1 fib1.f
 
-      or
+   or
 
-      ::
+   .. code-block:: sh
 
          f2py -m fib1 fib1.f -h fib1.pyf
          f2py -c fib1.pyf fib1.f
 
-      For more information, see `Building C and C++ Extensions`__ Python documentation for details.
+   For more information, see the `Building C and C++ Extensions`__ Python documentation for details.
 
-      __ https://docs.python.org/3/extending/building.html
+   __ https://docs.python.org/3/extending/building.html
 
 
    When building an extension module, a combination of the following
-   macros may be required for non-gcc Fortran compilers::
- 
+   macros may be required for non-gcc Fortran compilers:
+
+   .. code-block:: sh
+
      -DPREPEND_FORTRAN
      -DNO_APPEND_FORTRAN
      -DUPPERCASE_FORTRAN
@@ -197,11 +209,13 @@ distinguished by the usage of ``-c`` and ``-h`` switches:
    of an array argument is larger than ``<int>``, a message about
    the coping is sent to ``stderr``.
 
-Other options:
+Other options
+^^^^^^^^^^^^^
 
 ``-m <modulename>``
-  Name of an extension module. Default is ``untitled``. Don't use this option
-  if a signature file (\*.pyf) is used.
+  Name of an extension module. Default is ``untitled``.
+
+  .. warning:: Don't use this option if a signature file (\*.pyf) is used.
 ``--[no-]lower``
   Do [not] lower the cases in ``<fortran files>``.  By default,
   ``--lower`` is assumed with ``-h`` switch, and ``--no-lower``
@@ -214,7 +228,7 @@ Other options:
 ``--verbose``
   Run with extra verbosity.
 ``-v``
-  Print f2py version ID and exit.
+  Print the F2PY version and exit.
 
 Execute ``f2py`` without any options to get an up-to-date list of
 available options.