Moved scipy directory to numpy

48 files changed, 5166 insertions, 0 deletions

diff --git a/numpy/f2py/docs/FAQ.txt b/numpy/f2py/docs/FAQ.txt
new file mode 100644
index 000000000..e2ed79445
--- /dev/null
+++ b/numpy/f2py/docs/FAQ.txt
@@ -0,0 +1,615 @@
+
+======================================================================
+               F2PY Frequently Asked Questions
+======================================================================
+
+.. contents::
+
+General information
+===================
+
+Q: How to get started?
+----------------------
+
+First, install__ F2PY. Then check that F2PY installation works
+properly (see below__). Try out a `simple example`__.
+
+Read `F2PY Users Guide and Reference Manual`__. It contains lots
+of complete examples.
+
+If you have any questions/problems when using F2PY, don't hesitate to
+turn to `F2PY users mailing list`__ or directly to me.
+
+__ index.html#installation
+__ #testing
+__ index.html#usage
+__ usersguide/index.html
+__ index.html#mailing-list
+
+Q: When to report bugs?
+-----------------------
+
+* If F2PY scanning fails on Fortran sources that otherwise compile
+  fine.
+
+* After checking that you have the latest version of F2PY from its
+  CVS.  It is possible that a bug has been fixed already. See also the
+  log entries in the file `HISTORY.txt`_ (`HISTORY.txt in CVS`_).
+
+* After checking that your Python and Numerical Python installations
+  work correctly.
+
+* After checking that your C and Fortran compilers work correctly.
+
+
+Q: How to report bugs?
+----------------------
+
+You can send bug reports directly to me. Please, include information
+about your platform (operating system, version) and
+compilers/linkers, e.g. the output (both stdout/stderr) of
+::
+
+  python -c 'import f2py2e.diagnose;f2py2e.diagnose.run()'
+
+Feel free to add any other relevant information.  However, avoid
+sending the output of F2PY generated ``.pyf`` files (unless they are
+manually modified) or any binary files like shared libraries or object
+codes.
+
+While reporting bugs, you may find the following notes useful:
+
+* `How To Ask Questions The Smart Way`__ by E. S. Raymond and R. Moen.
+
+* `How to Report Bugs Effectively`__ by S. Tatham.
+
+__ http://www.catb.org/~esr/faqs/smart-questions.html
+__ http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
+
+Installation
+============
+
+Q: How to use F2PY with different Python versions?
+--------------------------------------------------
+
+Run the installation command using the corresponding Python
+executable. For example,
+::
+
+    python2.1 setup.py install
+
+installs the ``f2py`` script as ``f2py2.1``.
+
+See `Distutils User Documentation`__ for more information how to
+install Python modules to non-standard locations.
+
+__ http://www.python.org/sigs/distutils-sig/doc/inst/inst.html
+
+
+Q: Why F2PY is not working after upgrading?
+-------------------------------------------
+
+If upgrading from F2PY version 2.3.321 or earlier then remove all f2py
+specific files from ``/path/to/python/bin`` directory before
+running installation command.
+
+Q: How to get/upgrade scipy_distutils when using F2PY from CVS?
+---------------------------------------------------------------
+
+To get scipy_distutils from SciPy CVS repository, run
+::
+
+  cd cvs/f2py2e/
+  make scipy_distutils
+
+This will checkout scipy_distutils to the current directory.
+
+You can upgrade scipy_distutils by executing
+::
+
+  cd cvs/f2py2e/scipy_distutils
+  cvs update -Pd
+
+and install it by executing
+::
+
+  cd cvs/f2py2e/scipy_distutils
+  python setup_scipy_distutils.py install
+
+In most of the time, f2py2e and scipy_distutils can be upgraded
+independently.
+
+Testing
+=======
+
+Q: How to test if F2PY is installed correctly?
+----------------------------------------------
+
+Run
+::
+
+  f2py
+
+without arguments. If F2PY is installed correctly then it should print
+the usage information for f2py.
+
+Q: How to test if F2PY is working correctly?
+--------------------------------------------
+
+For a quick test, try out an example problem from Usage__
+section in `README.txt`_.
+
+__ index.html#usage
+
+For running F2PY unit tests, see `TESTING.txt`_.
+
+
+Q: How to run tests and examples in f2py2e/test-suite/ directory?
+---------------------------------------------------------------------
+
+You shouldn't. These tests are obsolete and I have no intention to
+make them work. They will be removed in future.
+
+
+Compiler/Platform-specific issues
+=================================
+
+Q: What are supported platforms and compilers?
+----------------------------------------------
+
+F2PY is developed on Linux system with a GCC compiler (versions
+2.95.x, 3.x). Fortran 90 related hooks are tested against Intel
+Fortran Compiler. F2PY should work under any platform where Python and
+Numeric are installed and has supported Fortran compiler installed.
+
+To see a list of supported compilers, execute::
+
+  f2py -c --help-fcompiler
+
+Example output::
+
+  List of available Fortran compilers:
+    --fcompiler=gnu    GNU Fortran Compiler (3.3.4)
+    --fcompiler=intel  Intel Fortran Compiler for 32-bit apps (8.0)
+  List of unavailable Fortran compilers:
+    --fcompiler=absoft   Absoft Corp Fortran Compiler
+    --fcompiler=compaq   Compaq Fortran Compiler
+    --fcompiler=compaqv  DIGITAL|Compaq Visual Fortran Compiler
+    --fcompiler=hpux     HP Fortran 90 Compiler
+    --fcompiler=ibm      IBM XL Fortran Compiler
+    --fcompiler=intele   Intel Fortran Compiler for Itanium apps
+    --fcompiler=intelev  Intel Visual Fortran Compiler for Itanium apps
+    --fcompiler=intelv   Intel Visual Fortran Compiler for 32-bit apps
+    --fcompiler=lahey    Lahey/Fujitsu Fortran 95 Compiler
+    --fcompiler=mips     MIPSpro Fortran Compiler
+    --fcompiler=nag      NAGWare Fortran 95 Compiler
+    --fcompiler=pg       Portland Group Fortran Compiler
+    --fcompiler=sun      Sun|Forte Fortran 95 Compiler
+    --fcompiler=vast     Pacific-Sierra Research Fortran 90 Compiler
+  List of unimplemented Fortran compilers:
+    --fcompiler=f  Fortran Company/NAG F Compiler
+  For compiler details, run 'config_fc --verbose' setup command.
+
+
+Q: How to use the F compiler in F2PY?
+-------------------------------------
+
+Read `f2py2e/doc/using_F_compiler.txt`__. It describes why the F
+compiler cannot be used in a normal way (i.e. using ``-c`` switch) to
+build F2PY generated modules. It also gives a workaround to this
+problem.
+
+__ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/doc/using_F_compiler.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup
+
+Q: How to use F2PY under Windows?
+---------------------------------
+
+F2PY can be used both within Cygwin__ and MinGW__ environments under
+Windows, F2PY can be used also in Windows native terminal.
+See the section `Setting up environment`__ for Cygwin and MinGW.
+
+__ http://cygwin.com/
+__ http://www.mingw.org/
+__ http://cens.ioc.ee/~pearu/scipy/BUILD_WIN32.html#setting-up-environment
+
+Install scipy_distutils and F2PY. Win32 installers of these packages
+are provided in `F2PY Download`__ section.
+
+__ http://cens.ioc.ee/projects/f2py2e/#download
+
+Use ``--compiler=`` and ``--fcompiler`` F2PY command line switches to
+to specify which C and Fortran compilers F2PY should use, respectively.
+
+Under MinGW environment, ``mingw32`` is default for a C compiler.
+
+Supported and Unsupported Features
+==================================
+
+Q: Does F2PY support ``ENTRY`` statements?
+------------------------------------------
+
+Yes, starting at F2PY version higher than 2.39.235_1706.
+
+Q: Does F2PY support derived types in F90 code?
+-----------------------------------------------
+
+Not yet. However I do have plans to implement support for F90 TYPE
+constructs in future. But note that the task in non-trivial and may
+require the next edition of F2PY for which I don't have resources to
+work with at the moment.
+
+Jeffrey Hagelberg from LLNL has made progress on adding 
+support for derived types to f2py. He writes:
+
+  At this point, I have a version of f2py that supports derived types
+  for most simple cases.  I have multidimensional arrays of derived
+  types and allocatable arrays of derived types working.  I'm just now
+  starting to work on getting nested derived types to work.  I also
+  haven't tried putting complex number in derived types yet.
+
+Hopefully he can contribute his changes to f2py soon.
+
+Q: Does F2PY support pointer data in F90 code?
+-----------------------------------------------
+
+No. I have never needed it and I haven't studied if there are any
+obstacles to add pointer data support to F2PY.
+
+Q: What if Fortran 90 code uses ``<type spec>(kind=KIND(..))``?
+---------------------------------------------------------------
+
+Currently, F2PY can handle only ``<type spec>(kind=<kindselector>)``
+declarations where ``<kindselector>`` is a numeric integer (e.g. 1, 2,
+4,...) but not a function call ``KIND(..)`` or any other
+expression. F2PY needs to know what would be the corresponding C type
+and a general solution for that would be too complicated to implement.
+
+However, F2PY provides a hook to overcome this difficulty, namely,
+users can define their own <Fortran type> to <C type> maps. For
+example, if Fortran 90 code contains::
+
+  REAL(kind=KIND(0.0D0)) ...
+
+then create a file ``.f2py_f2cmap`` (into the working directory)
+containing a Python dictionary::
+
+  {'real':{'KIND(0.0D0)':'double'}}
+
+for instance.
+
+Or more generally, the file ``.f2py_f2cmap`` must contain a dictionary
+with items::
+
+  <Fortran typespec> : {<selector_expr>:<C type>}
+
+that defines mapping between Fortran type::
+
+  <Fortran typespec>([kind=]<selector_expr>)
+
+and the corresponding ``<C type>``. ``<C type>`` can be one of the
+following::
+
+  char
+  signed_char
+  short
+  int
+  long_long
+  float
+  double
+  long_double
+  complex_float
+  complex_double
+  complex_long_double
+  string
+
+For more information, see ``f2py2e/capi_maps.py``.
+
+Related software
+================
+
+Q: How F2PY distinguishes from Pyfort?
+--------------------------------------
+
+F2PY and Pyfort have very similar aims and ideology of how they are
+targeted. Both projects started to evolve in the same year 1999
+independently. When we discovered each others projects, a discussion
+started to join the projects but that unfortunately failed for
+various reasons, e.g. both projects had evolved too far that merging
+the tools would have been impractical and giving up the efforts that
+the developers of both projects have made was unacceptable to both
+parties. And so, nowadays we have two tools for connecting Fortran
+with Python and this fact will hardly change in near future. To decide
+which one to choose is a matter of taste, I can only recommend to try
+out both to make up your choice.
+
+At the moment F2PY can handle more wrapping tasks than Pyfort,
+e.g. with F2PY one can wrap Fortran 77 common blocks, Fortran 90
+module routines, Fortran 90 module data (including allocatable
+arrays), one can call Python from Fortran, etc etc. F2PY scans Fortran
+codes to create signature (.pyf) files. F2PY is free from most of the
+limitations listed in in `the corresponding section of Pyfort
+Reference Manual`__.
+
+__ http://pyfortran.sourceforge.net/pyfort/pyfort_reference.htm#pgfId-296925
+
+There is a conceptual difference on how F2PY and Pyfort handle the
+issue of different data ordering in Fortran and C multi-dimensional
+arrays. Pyfort generated wrapper functions have optional arguments
+TRANSPOSE and MIRROR that can be used to control explicitly how the array
+arguments and their dimensions are passed to Fortran routine in order
+to deal with the C/Fortran data ordering issue. F2PY generated wrapper
+functions hide the whole issue from an end-user so that translation
+between Fortran and C/Python loops and array element access codes is
+one-to-one. How the F2PY generated wrappers deal with the issue is
+determined by a person who creates a signature file via using
+attributes like ``intent(c)``, ``intent(copy|overwrite)``,
+``intent(inout|in,out|inplace)`` etc.
+
+For example, let's consider a typical usage of both F2PY and Pyfort
+when wrapping the following simple Fortran code:
+
+.. include:: simple.f
+   :literal:
+
+The comment lines starting with ``cf2py`` are read by F2PY (so that we
+don't need to generate/handwrite an intermediate signature file in
+this simple case) while for a Fortran compiler they are just comment
+lines.
+
+And here is a Python version of the Fortran code:
+
+.. include:: pytest.py
+   :literal:
+
+To generate a wrapper for subroutine ``foo`` using F2PY, execute::
+
+  $ f2py -m f2pytest simple.f -c
+
+that will generate an extension module ``f2pytest`` into the current
+directory.
+
+To generate a wrapper using Pyfort, create the following file
+
+.. include:: pyforttest.pyf
+   :literal:
+
+and execute::
+
+  $ pyfort pyforttest
+
+In Pyfort GUI add ``simple.f`` to the list of Fortran sources and
+check that the signature file is in free format. And then copy
+``pyforttest.so`` from the build directory to the current directory.
+
+Now, in Python
+
+.. include:: simple_session.dat
+   :literal:
+
+Q: Can Pyfort .pyf files used with F2PY and vice versa?
+-------------------------------------------------------
+
+After some simple modifications, yes. You should take into account the
+following differences in Pyfort and F2PY .pyf files.
+
++ F2PY signature file contains ``python module`` and ``interface``
+  blocks that are equivalent to Pyfort ``module`` block usage.
+
++ F2PY attribute ``intent(inplace)`` is equivalent to Pyfort
+  ``intent(inout)``. F2PY ``intent(inout)`` is a strict (but safe)
+  version of ``intent(inplace)``, any mismatch in arguments with
+  expected type, size, or contiguouness will trigger an exception
+  while ``intent(inplace)`` (dangerously) modifies arguments
+  attributes in-place.
+
+Misc
+====
+
+Q: How to establish which Fortran compiler F2PY will use?
+---------------------------------------------------------
+
+This question may be releavant when using F2PY in Makefiles.  Here
+follows a script demonstrating how to determine which Fortran compiler
+and flags F2PY will use::
+
+  # Using post-0.2.2 scipy_distutils
+  from scipy_distutils.fcompiler import new_fcompiler
+  compiler = new_fcompiler() # or new_fcompiler(compiler='intel')
+  compiler.dump_properties()
+
+  # Using pre-0.2.2 scipy_distutils
+  import os
+  from scipy_distutils.command.build_flib import find_fortran_compiler
+  def main():
+      fcompiler = os.environ.get('FC_VENDOR')
+      fcompiler_exec = os.environ.get('F77')
+      f90compiler_exec = os.environ.get('F90')
+      fc = find_fortran_compiler(fcompiler,
+                                 fcompiler_exec,
+                                 f90compiler_exec,
+                                 verbose = 0)
+      print 'FC=',fc.f77_compiler
+      print 'FFLAGS=',fc.f77_switches
+      print 'FOPT=',fc.f77_opt
+  if __name__ == "__main__":
+      main()
+
+Users feedback
+==============
+
+Q: Where to find additional information on using F2PY?
+------------------------------------------------------
+
+There are several F2PY related tutorials, slides, papers, etc
+available:
+
++ `Fortran to Python Interface Generator with an Application to
+  Aerospace Engineering`__ by P. Peterson, J. R. R. A. Martins, and
+  J. J. Alonso in `In Proceedings of the 9th International Python
+  Conference`__, Long Beach, California, 2001.
+
+__ http://www.python9.org/p9-cdrom/07/index.htm
+__ http://www.python9.org/
+
++ Section `Adding Fortran90 code`__ in the UG of `The Bolometer Data
+  Analysis Project`__.
+
+__ http://www.astro.rub.de/laboca/download/boa_master_doc/7_4Adding_Fortran90_code.html
+__ http://www.openboa.de/
+
++ Powerpoint presentation `Python for Scientific Computing`__ by Eric
+  Jones in `The Ninth International Python Conference`__.
+
+__ http://www.python9.org/p9-jones.ppt
+__ http://www.python9.org/
+
++ Paper `Scripting a Large Fortran Code with Python`__ by Alvaro Caceres
+  Calleja in `International Workshop on Software Engineering for High
+  Performance Computing System Applications`__.
+
+__ http://csdl.ics.hawaii.edu/se-hpcs/pdf/calleja.pdf
+__ http://csdl.ics.hawaii.edu/se-hpcs/
+
++ Section `Automatic building of C/Fortran extension for Python`__ by
+  Simon Lacoste-Julien in `Summer 2002 Report about Hybrid Systems
+  Modelling`__.
+
+__ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html#tth_sEc3.4
+__ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html
+
++ `Scripting for Computational Science`__ by Hans Petter Langtangen
+   (see the `Mixed language programming`__ and `NumPy array programming`__
+   sections for examples on using F2PY).
+
+__ http://www.ifi.uio.no/~inf3330/lecsplit/
+__ http://www.ifi.uio.no/~inf3330/lecsplit/slide662.html
+__ http://www.ifi.uio.no/~inf3330/lecsplit/slide718.html
+
++  Chapters 5 and 9 of `Python Scripting for Computational Science`__
+   by H. P. Langtangen for case studies on using F2PY.
+
+__ http://www.springeronline.com/3-540-43508-5
+
++ Section `Fortran Wrapping`__ in `Continuity`__, a computational tool
+  for continuum problems in bioengineering and physiology.
+
+__ http://www.continuity.ucsd.edu/cont6_html/docs_fram.html
+__ http://www.continuity.ucsd.edu/
+
++ Presentation `PYFORT and F2PY: 2 ways to bind C and Fortran with Python`__
+  by Reiner Vogelsang.
+
+__ http://www.prism.enes.org/WPs/WP4a/Slides/pyfort/pyfort.html
+
++ Lecture slides of `Extending Python: speed it up`__.
+
+__ http://www.astro.uni-bonn.de/~heith/lecture_pdf/friedrich5.pdf
+
++ Wiki topics on `Wrapping Tools`__ and `Wrapping Bemchmarks`__ for Climate
+  System Center at the University of Chicago.
+
+__ https://geodoc.uchicago.edu/climatewiki/DiscussWrappingTools
+__ https://geodoc.uchicago.edu/climatewiki/WrappingBenchmarks
+
++ `Performance Python with Weave`__ by Prabhu Ramachandran.
+
+__ http://www.scipy.org/documentation/weave/weaveperformance.html
+
++ `How To Install py-f2py on Mac OSX`__
+
+__ http://py-f2py.darwinports.com/
+
+Please, let me know if there are any other sites that document F2PY
+usage in one or another way.
+
+Q: What projects use F2PY?
+--------------------------
+
++ `SciPy: Scientific tools for Python`__
+
+__ http://www.scipy.org/
+
++ `The Bolometer Data Analysis Project`__
+
+__ http://www.openboa.de/
+
++ `pywavelet`__
+
+__ http://www.met.wau.nl/index.html?http://www.met.wau.nl/medewerkers/moenea/python/pywavelet.html
+
++ `PyARTS: an ARTS related Python package`__.
+
+__ http://www.met.ed.ac.uk/~cory/PyARTS/
+
++ `Python interface to PSPLINE`__, a collection of Spline and
+  Hermite interpolation tools for 1D, 2D, and 3D datasets on
+  rectilinear grids. 
+
+__ http://pypspline.sourceforge.net
+
++ `Markovian Analysis Package for Python`__.
+
+__ http://pymc.sourceforge.net
+
++ `Modular toolkit for Data Processing (MDP)`__
+
+__ http://mdp-toolkit.sourceforge.net/
+
+
+Please, send me a note if you are using F2PY in your project.
+
+Q: What people think about F2PY?
+--------------------------------
+
+*F2PY is GOOD*:
+
+Here are some comments people have posted to f2py mailing list and c.l.py:
+
++ Ryan Krauss: I really appreciate f2py.  It seems weird to say, but I
+  am excited about relearning FORTRAN to compliment my python stuff.
+
++ Fabien Wahl: f2py is great, and is used extensively over here...
+
++ Fernando Perez: Anyway, many many thanks for this amazing tool.
+
+  I haven't used pyfort, but I can definitely vouch for the amazing quality of 
+  f2py.  And since f2py is actively used by scipy, it won't go unmaintained.  
+  It's quite impressive, and very easy to use.
+
++ Kevin Mueller: First off, thanks to those responsible for F2PY; 
+  its been an integral tool of my research for years now.
+
++ David Linke: Best regards and thanks for the great tool!
+
++ Perrin Meyer: F2Py is really useful!
+
++ Hans Petter Langtangen: First of all, thank you for developing
+  F2py. This is a very important contribution to the scientific
+  computing community. We are using F2py a lot and are very happy with
+  it.
+
++ Berthold Höllmann: Thank's alot. It seems it is also working in my
+  'real' application :-)
+
++ John Hunter: At first I wrapped them with f2py (unbelievably easy!)...
+
++ Cameron Laird: Among many other features, Python boasts a mature
+  f2py, which makes it particularly rewarding to yoke Fortran- and
+  Python-coded modules into finished applications.
+
++ Ryan Gutenkunst: f2py is sweet magic.
+
+*F2PY is BAD*:
+
++ `Is it worth using on a large scale python drivers for Fortran
+  subroutines, interfaced with f2py?`__
+
+__ http://sepwww.stanford.edu/internal/computing/python.html
+
+Additional comments on F2PY, good or bad, are welcome!
+
+.. References:
+.. _README.txt: index.html
+.. _HISTORY.txt: HISTORY.html
+.. _HISTORY.txt in CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+.. _TESTING.txt: TESTING.html
diff --git a/numpy/f2py/docs/HISTORY.txt b/numpy/f2py/docs/HISTORY.txt
new file mode 100644
index 000000000..876ab2362
--- /dev/null
+++ b/numpy/f2py/docs/HISTORY.txt
@@ -0,0 +1,1044 @@
+.. -*- rest -*-
+
+=========================
+ F2PY History
+=========================
+
+:Author: Pearu Peterson <pearu@cens.ioc.ee>
+:Web-site: http://cens.ioc.ee/projects/f2py2e/
+:Date: $Date: 2005/09/16 08:36:45 $
+:Revision: $Revision: 1.191 $
+
+.. Contents::
+
+Release 2.46.243
+=====================
+
+* common_rules.py
+
+  - Fixed compiler warnings.
+
+* fortranobject.c
+
+  - Fixed another dims calculation bug.
+  - Fixed dims calculation bug and added the corresponding check.
+  - Accept higher dimensional arrays if their effective rank matches.
+    Effective rank is multiplication of non-unit dimensions.
+
+* f2py2e.py
+
+  - Added support for scipy.distutils version 0.4.0.
+
+* Documentation
+
+  - Added example about ``intent(callback,hide)`` usage. Updates.
+  - Updated FAQ.
+
+* cb_rules.py
+
+  - Fixed missing need kw error.
+  - Fixed getting callback non-existing extra arguments.
+  - External callback functions and extra_args can be set via 
+    ext.module namespace.
+  - Avoid crash when external callback function is not set.
+
+* rules.py
+
+  - Enabled ``intent(out)`` for ``intent(aux)`` non-complex scalars.
+  - Fixed splitting lines in F90 fixed form mode.
+  - Fixed FORTRANAME typo, relevant when wrapping scalar functions with 
+    ``--no-wrap-functions``.
+  - Improved failure handling for callback functions.
+  - Fixed bug in writting F90 wrapper functions when a line length
+    is exactly 66.
+
+* cfuncs.py
+
+  - Fixed dependency issue with typedefs.
+  - Introduced ``-DUNDERSCORE_G77`` that cause extra underscore to be
+    used for external names that contain an underscore.
+
+* capi_maps.py
+
+  - Fixed typos.
+  - Fixed using complex cb functions.
+
+* crackfortran.py
+
+  - Introduced parent_block key. Get ``use`` statements recursively 
+    from parent blocks. 
+  - Apply parameter values to kindselectors.
+  - Fixed bug evaluating ``selected_int_kind`` function.
+  - Ignore Name and Syntax errors when evaluating scalars.
+  - Treat ``<int>_intType`` as ``<int>`` in get_parameters.
+  - Added support for F90 line continuation in fix format mode.
+  - Include optional attribute of external to signature file.
+  - Add ``entry`` arguments to variable lists.
+  - Treat \xa0 character as space.
+  - Fixed bug where __user__ callback subroutine was added to its
+    argument list.
+  - In strict 77 mode read only the first 72 columns.
+  - Fixed parsing ``v(i) = func(r)``.
+  - Fixed parsing ``integer*4::``.
+  - Fixed parsing ``1.d-8`` when used as a parameter value.
+
+Release 2.45.241_1926
+=====================
+
+* diagnose.py
+
+  - Clean up output.
+
+* cb_rules.py
+
+  - Fixed ``_cpointer`` usage for subroutines.
+  - Fortran function ``_cpointer`` can be used for callbacks.
+
+* func2subr.py
+
+  - Use result name when wrapping functions with subroutines.
+
+* f2py2e.py
+
+  - Fixed ``--help-link`` switch.
+  - Fixed ``--[no-]lower`` usage with ``-c`` option.
+  - Added support for ``.pyf.src`` template files.
+
+* __init__.py
+
+  - Using ``exec_command`` in ``compile()``.
+
+* setup.py
+
+  - Clean up.
+  - Disabled ``need_scipy_distutils`` function. From now on it is assumed
+    that proper version of ``scipy_distutils`` is already installed.
+
+* capi_maps.py
+
+  - Added support for wrapping unsigned integers. In a .pyf file
+    ``integer(-1)``, ``integer(-2)``, ``integer(-4)`` correspond to
+    ``unsigned char``, ``unsigned short``, ``unsigned`` C types,
+    respectively.
+
+* tests/c/return_real.py
+
+  - Added tests to wrap C functions returning float/double.
+
+* fortranobject.c
+
+  - Added ``_cpointer`` attribute to wrapped objects.
+
+* rules.py
+
+  - ``_cpointer`` feature for wrapped module functions is not
+    functional at the moment.
+  - Introduced ``intent(aux)`` attribute. Useful to save a value
+    of a parameter to auxiliary C variable. Note that ``intent(aux)``
+    implies ``intent(c)``. 
+  - Added ``usercode`` section. When ``usercode`` is used in ``python
+    module`` block twise then the contents of the second multi-line
+    block is inserted after the definition of external routines.
+  - Call-back function arguments can be CObjects.
+
+* cfuncs.py
+
+  - Allow call-back function arguments to be fortran objects.
+  - Allow call-back function arguments to be built-in functions.
+
+* crackfortran.py
+
+  - Fixed detection of a function signature from usage example.
+  - Cleaned up -h output for intent(callback) variables.
+  - Repair malformed argument list (missing argument name).
+  - Warn on the usage of multiple attributes without type specification.
+  - Evaluate only scalars ``<initexpr>`` (e.g. not of strings).
+  - Evaluate ``<initexpr>`` using parameters name space.
+  - Fixed resolving `<name>(<args>)[result(<result>)]` pattern.
+  - ``usercode`` can be used more than once in the same context.
+
+Release 2.43.239_1831
+=====================
+
+* auxfuncs.py
+
+  - Made ``intent(in,inplace)`` to mean ``intent(inplace)``.
+
+* f2py2e.py
+
+  - Intoduced ``--help-link`` and ``--link-<resource>``
+    switches to link generated extension module with system
+    ``<resource>`` as defined by scipy_distutils/system_info.py.
+
+* fortranobject.c
+
+  - Patch to make PyArray_CanCastSafely safe on 64-bit machines.
+    Fixes incorrect results when passing ``array('l')`` to 
+    ``real*8 intent(in,out,overwrite)`` arguments.
+
+* rules.py
+
+  - Avoid empty continuation lines in Fortran wrappers.
+
+* cfuncs.py
+
+  - Adding ``\0`` at the end of a space-padded string, fixes tests
+    on 64-bit Gentoo.
+
+* crackfortran.py
+
+  - Fixed splitting lines with string parameters.
+
+Release 2.43.239_1806
+=====================
+
+* Tests
+
+  - Fixed test site that failed after padding strings with spaces
+    instead of zeros.
+
+* Documentation
+
+  - Documented ``intent(inplace)`` attribute.
+  - Documented ``intent(callback)`` attribute.
+  - Updated FAQ, added Users Feedback section.
+
+* cfuncs.py
+
+  - Padding longer (than provided from Python side) strings with spaces
+    (that is Fortran behavior) instead of nulls (that is C strncpy behavior).
+
+* f90mod_rules.py
+
+  - Undoing rmbadnames in Python and Fortran layers.
+
+* common_rules.py
+
+  - Renaming common block items that have names identical to C keywords.
+  - Fixed wrapping blank common blocks.
+
+* fortranobject.h
+
+  - Updated numarray (0.9, 1.0, 1.1) support (patch by Todd Miller).
+
+* fortranobject.c
+
+  - Introduced ``intent(inplace)`` feature.
+  - Fix numarray reference counts (patch by Todd).
+  - Updated numarray (0.9, 1.0, 1.1) support (patch by Todd Miller).
+  - Enabled F2PY_REPORT_ON_ARRAY_COPY for Numarray.
+
+* capi_maps.py
+
+  - Always normalize .f2py_f2cmap keys to lower case.
+
+* rules.py
+
+  - Disabled ``index`` macro as it conflicts with the one defined
+    in string.h.
+  - Moved ``externroutines`` up to make it visible to ``usercode``.
+  - Fixed bug in f90 code generation: no empty line continuation is
+    allowed.
+  - Fixed undefined symbols failure when ``fortranname`` is used
+    to rename a wrapped function.
+  - Support for ``entry`` statement.
+
+* auxfuncs.py
+
+  - Made is* functions more robust with respect to parameters that
+    have no typespec specified.
+  - Using ``size_t`` instead of ``int`` as the type of string
+    length. Fixes issues on 64-bit platforms.
+
+* setup.py
+
+  - Fixed bug of installing ``f2py`` script as ``.exe`` file.
+
+* f2py2e.py
+
+  - ``--compiler=`` and ``--fcompiler=`` can be specified at the same time.
+
+* crackfortran.py
+
+  - Fixed dependency detection for non-intent(in|inout|inplace) arguments.
+    They must depend on their dimensions, not vice-versa.
+  - Don't match ``!!f2py`` as a start of f2py directive.
+  - Only effective intent attributes will be output to ``-h`` target.
+  - Introduced ``intent(callback)`` to build interface between Python
+    functions and Fortran external routines.
+  - Avoid including external arguments to __user__ modules.
+  - Initial hooks to evaluate ``kind`` and ``selected_int_kind``.
+  - Evaluating parameters in {char,kind}selectors and applying rmbadname.
+  - Evaluating parameters using also module parameters. Fixed the order
+    of parameter evaluation.
+  - Fixed silly bug: when block name was not lower cased, it was not
+    recognized correctly.
+  - Applying mapping '.false.'->'False', '.true.'->'True' to logical
+    parameters. TODO: Support for logical expressions is needed.
+  - Added support for multiple statements in one line (separated with semicolon).
+  - Impl. get_useparameters function for using parameter values from
+    other f90 modules.
+  - Applied Bertholds patch to fix bug in evaluating expressions 
+    like ``1.d0/dvar``.
+  - Fixed bug in reading string parameters.
+  - Evaluating parameters in charselector. Code cleanup.
+  - Using F90 module parameters to resolve kindselectors.
+  - Made the evaluation of module data init-expression more robust.
+  - Support for ``entry`` statement.
+  - Fixed ``determineexprtype`` that in the case of parameters 
+    returned non-dictionary objects.
+  - Use ``-*- fix -*-`` to specify that a file is in fixed format.
+
+Release 2.39.235_1693
+=====================
+
+* fortranobject.{h,c}
+
+  - Support for allocatable string arrays.
+
+* cfuncs.py
+
+  - Call-back arguments can now be also instances that have ``__call__`` method
+    as well as instance methods.
+
+* f2py2e.py
+
+  - Introduced ``--include_paths <path1>:<path2>:..`` command line
+    option.
+  - Added ``--compiler=`` support to change the C/C++ compiler from
+    f2py command line.
+
+* capi_maps.py
+
+  - Handle ``XDY`` parameter constants.
+
+* crackfortran.py
+
+  - Handle ``XDY`` parameter constants.
+
+  - Introduced formatpattern to workaround a corner case where reserved 
+    keywords are used in format statement. Other than that, format pattern
+    has no use.
+
+  - Parameters are now fully evaluated.
+
+* More splitting of documentation strings.
+
+* func2subr.py - fixed bug for function names that f77 compiler
+  would set ``integer`` type.
+
+Release 2.39.235_1660
+=====================
+
+* f2py2e.py
+
+  - Fixed bug in using --f90flags=..
+
+* f90mod_rules.py
+
+  - Splitted generated documentation strings (to avoid MSVC issue when
+    string length>2k)
+
+  - Ignore ``private`` module data.
+
+Release 2.39.235_1644
+=====================
+
+:Date:24 February 2004
+
+* Character arrays:
+
+  - Finished complete support for character arrays and arrays of strings.
+  - ``character*n a(m)`` is treated like ``character a(m,n)`` with ``intent(c)``.
+  - Character arrays are now considered as ordinary arrays (not as arrays
+    of strings which actually didn't work).
+
+* docs
+
+  - Initial f2py manpage file f2py.1.
+  - Updated usersguide and other docs when using scipy_distutils 0.2.2
+    and up.
+
+* capi_maps.py
+
+  - Try harder to use .f2py_f2cmap mappings when kind is used.
+
+* crackfortran.py
+
+  - Included files are first search in the current directory and
+    then from the source file directory.
+  - Ignoring dimension and character selector changes.
+  - Fixed bug in Fortran 90 comments of fixed format.
+  - Warn when .pyf signatures contain undefined symbols.
+  - Better detection of source code formats. Using ``-*- fortran -*-``
+    or ``-*- f90 -*-`` in the first line of a Fortran source file is 
+    recommended to help f2py detect the format, fixed or free,
+    respectively, correctly.
+
+* cfuncs.py
+
+  - Fixed intent(inout) scalars when typecode=='l'.
+  - Fixed intent(inout) scalars when not using numarray.
+  - Fixed intent(inout) scalars when using numarray.
+
+* diagnose.py
+
+  - Updated for scipy_distutils 0.2.2 and up.
+  - Added numarray support to diagnose.
+
+* fortranobject.c
+
+  - Fixed nasty bug with intent(in,copy) complex slice arrays.
+  - Applied Todd's patch to support numarray's byteswapped or
+    misaligned arrays, requires numarray-0.8 or higher.
+
+* f2py2e.py
+
+  - Applying new hooks for scipy_distutils 0.2.2 and up, keeping
+    backward compatibility with depreciation messages.
+  - Using always os.system on non-posix platforms in f2py2e.compile
+    function.
+
+* rules.py
+
+  - Changed the order of buildcallback and usercode junks.
+
+* setup.cfg
+
+  - Added so that docs/ and tests/ directories are included to RPMs.
+
+* setup.py
+
+  - Installing f2py.py instead of f2py.bat under NT.   
+  - Introduced ``--with-scipy_distutils`` that is useful when making
+    f2py tar-ball with scipy_distutils included.
+
+Release 2.37.233-1545
+=====================
+
+:Date: 11 September 2003
+
+* rules.py
+
+  - Introduced ``interface_usercode`` replacement. When ``usercode``
+    statement is used inside the first interface block, its contents
+    will be inserted at the end of initialization function of a F2PY
+    generated extension module (feature request: Berthold Höllmann).
+  - Introduced auxiliary function ``as_column_major_storage`` that
+    converts input array to an array with column major storage order
+    (feature request: Hans Petter Langtangen).
+
+* crackfortran.py
+
+  - Introduced ``pymethoddef`` statement.
+
+* cfuncs.py
+
+  - Fixed "#ifdef in #define TRYPYARRAYTEMPLATE" bug (patch thanks
+    to Bernhard Gschaider)
+
+* auxfuncs.py
+
+  - Introduced ``getpymethod`` function.
+  - Enabled multi-line blocks in ``callprotoargument`` statement.
+
+* f90mod_rules.py
+
+  - Undone "Fixed Warning 43 emitted by Intel Fortran compiler" that
+    causes (curios) segfaults.
+
+* fortranobject.c
+
+  - Fixed segfaults (that were introduced with recent memory leak
+    fixes) when using allocatable arrays.
+  - Introduced F2PY_REPORT_ON_ARRAY_COPY CPP macro int-variable. If defined 
+    then a message is printed to stderr whenever a copy of an array is
+    made and arrays size is larger than F2PY_REPORT_ON_ARRAY_COPY.
+
+Release 2.35.229-1505
+=====================
+
+:Date: 5 August 2003
+
+* General
+
+  - Introduced ``usercode`` statement (dropped ``c_code`` hooks).
+
+* setup.py
+
+  - Updated the CVS location of scipy_distutils.
+
+* auxfuncs.py
+
+  - Introduced ``isint1array(var)`` for fixing ``integer*1 intent(out)``
+    support.
+
+* tests/f77/callback.py
+
+  Introduced some basic tests.
+
+* src/fortranobject.{c,h}
+
+  - Fixed memory leaks when getting/setting allocatable arrays.
+    (Bug report by Bernhard Gschaider)
+
+  - Initial support for numarray (Todd Miller's patch). Use -DNUMARRAY
+    on the f2py command line to enable numarray support. Note that
+    there is no character arrays support and these hooks are not
+    tested with F90 compilers yet.
+
+* cfuncs.py
+
+  - Fixed reference counting bug that appeared when constructing extra
+    argument list to callback functions.
+  - Added ``PyArray_LONG != PyArray_INT`` test.
+
+* f2py2e.py
+
+  Undocumented ``--f90compiler``.
+
+* crackfortran.py
+
+  - Introduced ``usercode`` statement.
+  - Fixed newlines when outputting multi-line blocks.
+  - Optimized ``getlincoef`` loop and ``analyzevars`` for cases where
+    len(vars) is large.
+  - Fixed callback string argument detection.
+  - Fixed evaluating expressions: only int|float expressions are
+    evaluated succesfully.
+
+* docs
+
+  Documented -DF2PY_REPORT_ATEXIT feature.
+
+* diagnose.py
+
+  Added CPU information and sys.prefix printout.
+
+* tests/run_all.py
+
+  Added cwd to PYTHONPATH.
+
+* tests/f??/return_{real,complex}.py
+
+  Pass "infinity" check in SunOS.
+
+* rules.py
+
+  - Fixed ``integer*1 intent(out)`` support
+  - Fixed free format continuation of f2py generated F90 files.
+
+* tests/mixed/
+
+  Introduced tests for mixing Fortran 77, Fortran 90 fixed and free
+  format codes in one module.
+
+* f90mod_rules.py
+
+  - Fixed non-prototype warnings.
+  - Fixed Warning 43 emitted by Intel Fortran compiler.
+  - Avoid long lines in Fortran codes to reduce possible problems with
+    continuations of lines.
+
+Public Release 2.32.225-1419
+============================
+
+:Date: 8 December 2002
+
+* docs/usersguide/
+
+  Complete revision of F2PY Users Guide  
+
+* tests/run_all.py
+
+  - New file. A Python script to run all f2py unit tests.
+
+* Removed files: buildmakefile.py, buildsetup.py.
+
+* tests/f77/
+
+  - Added intent(out) scalar tests.
+
+* f2py_testing.py
+
+  - Introduced. It contains jiffies, memusage, run, cmdline functions
+    useful for f2py unit tests site.
+
+* setup.py
+
+  - Install scipy_distutils only if it is missing or is too old
+    for f2py.
+
+* f90modrules.py
+
+  - Fixed wrapping f90 module data.
+  - Fixed wrapping f90 module subroutines.
+  - Fixed f90 compiler warnings for wrapped functions by using interface
+    instead of external stmt for functions.
+
+* tests/f90/
+
+  - Introduced return_*.py tests.
+
+* func2subr.py
+
+  - Added optional signature argument to createfuncwrapper.
+  - In f2pywrappers routines, declare external, scalar, remaining
+    arguments in that order. Fixes compiler error 'Invalid declaration'
+    for::
+
+      real function foo(a,b)
+      integer b
+      real a(b)
+      end
+
+* crackfortran.py
+
+  - Removed first-line comment information support.
+  - Introduced multiline block. Currently usable only for
+    ``callstatement`` statement.
+  - Improved array length calculation in getarrlen(..).
+  - "From sky" program group is created only if ``groupcounter<1``. 
+    See TODO.txt. 
+  - Added support for ``dimension(n:*)``, ``dimension(*:n)``. They are
+    treated as ``dimesnion(*)`` by f2py.
+  - Fixed parameter substitution (this fixes TODO item by Patrick
+    LeGresley, 22 Aug 2001).
+
+* f2py2e.py
+
+  - Disabled all makefile, setup, manifest file generation hooks.
+  - Disabled --[no]-external-modroutines option. All F90 module
+    subroutines will have Fortran/C interface hooks.
+  - --build-dir can be used with -c option.
+  - only/skip modes can be used with -c option.
+  - Fixed and documented `-h stdout` feature.
+  - Documented extra options.
+  - Introduced --quiet and --verbose flags.
+
+* cb_rules.py
+
+  - Fixed debugcapi hooks for intent(c) scalar call-back arguments
+    (bug report: Pierre Schnizer).
+  - Fixed intent(c) for scalar call-back arguments.
+  - Improved failure reports.
+
+* capi_maps.py
+
+  - Fixed complex(kind=..) to C type mapping bug. The following hold
+    complex==complex(kind=4)==complex*8, complex(kind=8)==complex*16
+  - Using signed_char for integer*1 (bug report: Steve M. Robbins).
+  - Fixed logical*8 function bug: changed its C correspondence to
+    long_long.
+  - Fixed memory leak when returning complex scalar.
+
+* __init__.py
+
+  - Introduced a new function (for f2py test site, but could be useful
+    in general) ``compile(source[,modulename,extra_args])`` for
+    compiling fortran source codes directly from Python.
+
+* src/fortranobject.c
+
+  - Multi-dimensional common block members and allocatable arrays 
+    are returned as Fortran-contiguous arrays.
+  - Fixed NULL return to Python without exception.
+  - Fixed memory leak in getattr(<fortranobj>,'__doc__').
+  - <fortranobj>.__doc__ is saved to <fortranobj>.__dict__ (previously
+    it was generated each time when requested).
+  - Fixed a nasty typo from the previous item that caused data
+    corruption and occasional SEGFAULTs.
+  - array_from_pyobj accepts arbitrary rank arrays if the last dimension
+    is undefined. E.g. dimension(3,*) accepts a(3,4,5) and the result is
+    array with dimension(3,20).
+  - Fixed (void*) casts to make g++ happy (bug report: eric).
+  - Changed the interface of ARR_IS_NULL macro to avoid "``NULL used in
+    arithmetics``" warnings from g++.
+
+* src/fortranobject.h
+
+  - Undone previous item. Defining NO_IMPORT_ARRAY for
+    src/fortranobject.c (bug report: travis)
+  - Ensured that PY_ARRAY_UNIQUE_SYMBOL is defined only for
+    src/fortranobject.c (bug report: eric).
+
+* rules.py
+
+  - Introduced dummy routine feature.
+  - F77 and F90 wrapper subroutines (if any) as saved to different
+    files, <modulename>-f2pywrappers.f and <modulename>-f2pywrappers2.f90,
+    respectively. Therefore, wrapping F90 requires scipy_distutils >= 
+    0.2.0_alpha_2.229.
+  - Fixed compiler warnings about meaningless ``const void (*f2py_func)(..)``.
+  - Improved error messages for ``*_from_pyobj``.
+  - Changed __CPLUSPLUS__ macros to __cplusplus (bug report: eric).
+  - Changed (void*) casts to (f2py_init_func) (bug report: eric).
+  - Removed unnecessary (void*) cast for f2py_has_column_major_storage
+    in f2py_module_methods definition (bug report: eric).
+  - Changed the interface of f2py_has_column_major_storage function:
+    removed const from the 1st argument.
+
+* cfuncs.py
+
+  - Introduced -DPREPEND_FORTRAN.
+  - Fixed bus error on SGI by using PyFloat_AsDouble when ``__sgi`` is defined.
+    This seems to be `know bug`__ with Python 2.1 and SGI.
+  - string_from_pyobj accepts only arrays whos elements size==sizeof(char).
+  - logical scalars (intent(in),function) are normalized to 0 or 1.
+  - Removed NUMFROMARROBJ macro.
+  - (char|short)_from_pyobj now use int_from_pyobj.
+  - (float|long_double)_from_pyobj now use double_from_pyobj.
+  - complex_(float|long_double)_from_pyobj now use complex_double_from_pyobj.
+  - Rewrote ``*_from_pyobj`` to be more robust. This fixes segfaults if
+    getting * from a string. Note that int_from_pyobj differs 
+    from PyNumber_Int in that it accepts also complex arguments 
+    (takes the real part) and sequences (takes the 1st element). 
+  - Removed unnecessary void* casts in NUMFROMARROBJ.
+  - Fixed casts in ``*_from_pyobj`` functions.
+  - Replaced CNUMFROMARROBJ with NUMFROMARROBJ.
+
+.. __: http://sourceforge.net/tracker/index.php?func=detail&aid=435026&group_id=5470&atid=105470
+
+* auxfuncs.py
+
+  - Introduced isdummyroutine().
+  - Fixed islong_* functions.
+  - Fixed isintent_in for intent(c) arguments (bug report: Pierre Schnizer).
+  - Introduced F2PYError and throw_error. Using throw_error, f2py 
+    rejects illegal .pyf file constructs that otherwise would cause
+    compilation failures or python crashes.
+  - Fixed islong_long(logical*8)->True.
+  - Introduced islogical() and islogicalfunction().
+  - Fixed prototype string argument (bug report: eric).
+
+* Updated README.txt and doc strings. Starting to use docutils.
+
+* Speed up for ``*_from_pyobj`` functions if obj is a sequence.
+
+* Fixed SegFault (reported by M.Braun) due to invalid ``Py_DECREF`` 
+  in ``GETSCALARFROMPYTUPLE``.
+
+Older Releases
+==============
+
+::
+
+ *** Fixed missing includes when wrapping F90 module data.
+ *** Fixed typos in docs of build_flib options.
+ *** Implemented prototype calculator if no callstatement or
+    callprotoargument statements are used. A warning is issued if
+    callstatement is used without callprotoargument.
+ *** Fixed transposing issue with array arguments in callback functions.
+ *** Removed -pyinc command line option.
+ *** Complete tests for Fortran 77 functions returning scalars.
+ *** Fixed returning character bug if --no-wrap-functions.
+ *** Described how to wrap F compiled Fortran F90 module procedures
+    with F2PY. See doc/using_F_compiler.txt.
+ *** Fixed the order of build_flib options when using --fcompiler=...
+ *** Recognize .f95 and .F95 files as Fortran sources with free format.
+ *** Cleaned up the output of 'f2py -h': removed obsolete items,
+    added build_flib options section. 
+ *** Added --help-compiler option: it lists available Fortran compilers
+    as detected by scipy_distutils/command/build_flib.py. This option
+    is available only with -c option.
+
+
+:Release: 2.13.175-1250
+:Date: 4 April 2002
+
+::
+
+ *** Fixed copying of non-contigious 1-dimensional arrays bug. 
+    (Thanks to Travis O.).
+
+
+:Release: 2.13.175-1242
+:Date: 26 March 2002
+
+::
+
+ *** Fixed ignoring type declarations.
+ *** Turned F2PY_REPORT_ATEXIT off by default.
+ *** Made MAX,MIN macros available by default so that they can be
+    always used in signature files. 
+ *** Disabled F2PY_REPORT_ATEXIT for FreeBSD.
+
+
+:Release: 2.13.175-1233
+:Date: 13 March 2002
+
+::
+
+ *** Fixed Win32 port when using f2py.bat. (Thanks to Erik Wilsher).
+ *** F2PY_REPORT_ATEXIT is disabled for MACs.
+ *** Fixed incomplete dependency calculator.
+
+
+:Release: 2.13.175-1222
+:Date: 3 March 2002
+
+::
+
+ *** Plugged a memory leak for intent(out) arrays with overwrite=0.
+ *** Introduced CDOUBLE_to_CDOUBLE,.. functions for copy_ND_array.
+    These cast functions probably work incorrectly in Numeric.
+
+
+:Release: 2.13.175-1212
+:Date: 23 February 2002
+
+::
+
+ *** Updated f2py for the latest scipy_distutils.
+ *** A nasty bug with multi-dimensional Fortran arrays is fixed
+    (intent(out) arrays had wrong shapes). (Thanks to Eric for 
+    pointing out this bug).
+ *** F2PY_REPORT_ATEXIT is disabled by default for __WIN32__.
+
+
+:Release: 2.11.174-1161
+:Date: 14 February 2002
+
+::
+
+ *** Updated f2py for the latest scipy_distutils.
+ *** Fixed raise error when f2py missed -m flag.
+ *** Script name `f2py' now depends on the name of python executable.
+    For example, `python2.2 setup.py install' will create a f2py
+    script with a name `f2py2.2'.
+ *** Introduced 'callprotoargument' statement so that proper prototypes
+    can be declared. This is crucial when wrapping C functions as it
+    will fix segmentation faults when these wrappers use non-pointer
+    arguments (thanks to R. Clint Whaley for explaining this to me). 
+    Note that in f2py generated wrapper, the prototypes have
+    the following forms: 
+       extern #rtype# #fortranname#(#callprotoargument#);
+    or
+       extern #rtype# F_FUNC(#fortranname#,#FORTRANNAME#)(#callprotoargument#);
+ *** Cosmetic fixes to F2PY_REPORT_ATEXIT feature.
+
+
+:Release: 2.11.174-1146
+:Date: 3 February 2002
+
+::
+
+ *** Reviewed reference counting in call-back mechanism. Fixed few bugs.
+ *** Enabled callstatement for complex functions.
+ *** Fixed bug with initializing capi_overwrite_<varname>
+ *** Introduced intent(overwrite) that is similar to intent(copy) but
+    has opposite effect. Renamed copy_<name>=1 to overwrite_<name>=0.
+    intent(overwrite) will make default overwrite_<name>=1.
+ *** Introduced intent(in|inout,out,out=<name>) attribute that renames
+    arguments name when returned. This renaming has effect only in
+    documentation strings. 
+ *** Introduced 'callstatement' statement to pyf file syntax. With this
+    one can specify explicitly how wrapped function should be called
+    from the f2py generated module. WARNING: this is a dangerous feature
+    and should be used with care. It is introduced to provide a hack
+    to construct wrappers that may have very different signature
+    pattern from the wrapped function. Currently 'callstatement' can
+    be used only inside a subroutine or function block (it should be enough
+    though) and must be only in one continuous line. The syntax of the
+    statement is:    callstatement <C-expression>;
+    
+
+:Release: 2.11.174
+:Date: 18 January 2002
+
+::
+
+ *** Fixed memory-leak for PyFortranObject.
+ *** Introduced extra keyword argument copy_<varname> for intent(copy)
+    variables. It defaults to 1 and forces to make a copy for
+    intent(in) variables when passing on to wrapped functions (in case
+    they undesirably change the variable in-situ). 
+ *** Introduced has_column_major_storage member function for all f2py
+    generated extension modules. It is equivalent to Python call
+    'transpose(obj).iscontiguous()' but very efficient.
+ *** Introduced -DF2PY_REPORT_ATEXIT. If this is used when compiling,
+    a report is printed to stderr as python exits. The report includes
+    the following timings: 
+    1) time spent in all wrapped function calls; 
+    2) time spent in f2py generated interface around the wrapped
+    functions. This gives a hint whether one should worry
+    about storing data in proper order (C or Fortran).
+    3) time spent in Python functions called by wrapped functions
+    through call-back interface.
+    4) time spent in f2py generated call-back interface.
+    For now, -DF2PY_REPORT_ATEXIT is enabled by default. Use 
+    -DF2PY_REPORT_ATEXIT_DISABLE to disable it (I am not sure if
+    Windows has needed tools, let me know). 
+    Also, I appreciate if you could send me the output of 'F2PY
+    performance report' (with CPU and platform information) so that I
+    could optimize f2py generated interfaces for future releases.
+ *** Extension modules can be linked with dmalloc library. Use
+    -DDMALLOC when compiling.
+ *** Moved array_from_pyobj to fortranobject.c.
+ *** Usage of intent(inout) arguments is made more strict -- only
+    with proper type contiguous arrays are accepted. In general,
+    you should avoid using intent(inout) attribute as it makes
+    wrappers of C and Fortran functions asymmetric. I recommend using
+    intent(in,out) instead.
+ *** intent(..) has new keywords: copy,cache.
+    intent(copy,in) - forces a copy of an input argument; this
+      may be useful for cases where the wrapped function changes
+      the argument in situ and this may not be desired side effect.
+      Otherwise, it is safe to not use intent(copy) for the sake
+      of a better performance. 
+    intent(cache,hide|optional) - just creates a junk of memory. 
+      It does not care about proper storage order. Can be also
+      intent(in) but then the corresponding argument must be a
+      contiguous array with a proper elsize.
+ *** intent(c) can be used also for subroutine names so that
+    -DNO_APPEND_FORTRAN can be avoided for C functions.
+
+ *** IMPORTANT BREAKING GOOD ... NEWS!!!: 
+
+    From now on you don't have to worry about the proper storage order
+    in multi-dimensional arrays that was earlier a real headache when
+    wrapping Fortran functions. Now f2py generated modules take care
+    of the proper conversations when needed. I have carefully designed
+    and optimized this interface to avoid any unnecessary memory usage
+    or copying of data. However, it is wise to use input arrays that
+    has proper storage order: for C arguments it is row-major and for
+    Fortran arguments it is column-major. But you don't need to worry
+    about that when developing your programs. The optimization of
+    initializing the program with proper data for possibly better
+    memory usage can be safely postponed until the program is working.
+
+    This change also affects the signatures in .pyf files. If you have
+    created wrappers that take multi-dimensional arrays in arguments,
+    it is better to let f2py re-generate these files. Or you have to
+    manually do the following changes: reverse the axes indices in all
+    'shape' macros. For example, if you have defined an array A(n,m)
+    and n=shape(A,1), m=shape(A,0) then you must change the last
+    statements to n=shape(A,0), m=shape(A,1).
+
+
+:Release: 2.8.172
+:Date: 13 January 2002
+
+::
+
+ *** Fixed -c process. Removed pyf_extensions function and pyf_file class.
+ *** Reorganized setup.py. It generates f2py or f2py.bat scripts
+    depending on the OS and the location of the python executable.
+ *** Started to use update_version from scipy_distutils that makes
+    f2py startup faster. As a side effect, the version number system
+    changed.
+ *** Introduced test-site/test_f2py2e.py script that runs all
+    tests.
+ *** Fixed global variables initialization problem in crackfortran 
+    when run_main is called several times.
+ *** Added 'import Numeric' to C/API init<module> function.
+ *** Fixed f2py.bat in setup.py.
+ *** Switched over to scipy_distutils and dropped fortran_support.
+ *** On Windows create f2py.bat file.
+ *** Introduced -c option: read fortran or pyf files, construct extension
+    modules, build, and save them to current directory. 
+    In one word: do-it-all-in-one-call.
+ *** Introduced pyf_extensions(sources,f2py_opts) function. It simplifies
+    the extension building process considerably. Only for internal use.
+ *** Converted tests to use scipy_distutils in order to improve portability:
+    a,b,c
+ *** f2py2e.run_main() returns a pyf_file class instance containing
+    information about f2py generated files.
+ *** Introduced `--build-dir <dirname>' command line option.
+ *** Fixed setup.py for bdist_rpm command.
+ *** Added --scipy-setup command line option.
+ *** Fixed crackfortran that did not recognized capitalized type
+    specification with --no-lower flag.
+ *** `-h stdout' writes signature to stdout.
+ *** Fixed incorrect message for check() with empty name list.
+
+
+:Release: 2.4.366
+:Date: 17 December 2001
+
+::
+
+ *** Added command line option --[no-]manifest.
+ *** `make test' should run on Windows, but the results are not truthful.
+ *** Reorganized f2py2e.py a bit. Introduced run_main(comline_list) function
+    that can be useful when running f2py from another Python module.
+ *** Removed command line options -f77,-fix,-f90 as the file format
+    is determined from the extension of the fortran file
+    or from its header (first line starting with `!%' and containing keywords
+    free, fix, or f77). The later overrides the former one.
+ *** Introduced command line options --[no-]makefile,--[no-]latex-doc.
+    Users must explicitly use --makefile,--latex-doc if Makefile-<modulename>,
+    <modulename>module.tex is desired. --setup is default. Use --no-setup
+    to disable setup_<modulename>.py generation. --overwrite-makefile
+    will set --makefile.
+ *** Added `f2py_rout_' to #capiname# in rules.py.
+ *** intent(...) statement with empty namelist forces intent(...) attribute for
+    all arguments.
+ *** Dropped DL_IMPORT and DL_EXPORT in fortranobject.h.
+ *** Added missing PyFortran_Type.ob_type initialization.
+ *** Added gcc-3.0 support.
+ *** Raising non-existing/broken Numeric as a FatalError exception.
+ *** Fixed Python 2.x specific += construct in fortran_support.py.
+ *** Fixed copy_ND_array for 1-rank arrays that used to call calloc(0,..)
+    and caused core dump with a non-gcc compiler (Thanks to Pierre Schnizer
+    for reporting this bug).
+ *** Fixed "warning: variable `..' might be clobbered by `longjmp' or `vfork'":
+  - Reorganized the structure of wrapper functions to get rid of 
+    `goto capi_fail' statements that caused the above warning.
+
+
+:Release: 2.3.343
+:Date: 12 December 2001
+
+::
+
+ *** Issues with the Win32 support (thanks to Eric Jones and Tiffany Kamm):
+  -  Using DL_EXPORT macro for init#modulename#.
+  -  Changed PyObject_HEAD_INIT(&PyType_Type) to PyObject_HEAD_INIT(0).
+  -  Initializing #name#_capi=NULL instead of Py_None in cb hooks.
+ *** Fixed some 'warning: function declaration isn't a prototype', mainly
+    in fortranobject.{c,h}.
+ *** Fixed 'warning: missing braces around initializer'.
+ *** Fixed reading a line containing only a label.
+ *** Fixed nonportable 'cp -fv' to shutil.copy in f2py2e.py.
+ *** Replaced PyEval_CallObject with PyObject_CallObject in cb_rules.
+ *** Replaced Py_DECREF with Py_XDECREF when freeing hidden arguments.
+    (Reason: Py_DECREF caused segfault when an error was raised)
+ *** Impl. support for `include "file"' (in addition to `include 'file'')
+ *** Fixed bugs (buildsetup.py missing in Makefile, in generated MANIFEST.in)
+
+
+:Release: 2.3.327
+:Date: 4 December 2001
+
+::
+
+ *** Sending out the third public release of f2py.
+ *** Support for Intel(R) Fortran Compiler (thanks to Patrick LeGresley).
+ *** Introduced `threadsafe' statement to pyf-files (or to be used with
+    the 'f2py' directive in fortran codes) to force
+    Py_BEGIN|END_ALLOW_THREADS block around the Fortran subroutine
+    calling statement in Python C/API. `threadsafe' statement has
+    an effect only inside a subroutine block.
+ *** Introduced `fortranname <name>' statement to be used only within
+    pyf-files. This is useful when the wrapper (Python C/API) function
+    has different name from the wrapped (Fortran) function.
+ *** Introduced `intent(c)' directive and statement. It is useful when
+    wrapping C functions. Use intent(c) for arguments that are
+    scalars (not pointers) or arrays (with row-ordering of elements).
+
+
+:Release: 2.3.321
+:Date: 3 December 2001
+
+::
+
+ *** f2py2e can be installed using distutils (run `python setup.py install').
+ *** f2py builds setup_<modulename>.py. Use --[no-]setup to control this
+    feature. setup_<modulename>.py uses fortran_support module (from SciPy),
+    but for your convenience it is included also with f2py as an additional
+    package. Note that it has not as many compilers supported as with
+    using Makefile-<modulename>, but new compilers should be added to 
+    fortran_support module, not to f2py2e package.
+ *** Fixed some compiler warnings about else statements.
+
diff --git a/numpy/f2py/docs/OLDNEWS.txt b/numpy/f2py/docs/OLDNEWS.txt
new file mode 100644
index 000000000..b21215464
--- /dev/null
+++ b/numpy/f2py/docs/OLDNEWS.txt
@@ -0,0 +1,63 @@
+
+.. topic:: Old F2PY NEWS
+
+  March 30, 2004
+    F2PY bug fix release (version 2.39.235-1693). Two new command line switches:
+    ``--compiler`` and ``--include_paths``. Support for allocatable string arrays.
+    Callback arguments may now be arbitrary callable objects. Win32 installers
+    for F2PY and Scipy_core are provided.
+    `Differences with the previous release (version 2.37.235-1660)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.98&r2=1.87&f=h
+
+
+  March 9, 2004
+    F2PY bug fix release (version 2.39.235-1660).
+    `Differences with the previous release (version 2.37.235-1644)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.87&r2=1.83&f=h
+
+  February 24, 2004
+    Latest F2PY release (version 2.39.235-1644).
+    Support for scipy_distutils 0.2.2 and up (e.g. compiler flags can be
+    changed via f2py command line options). Implemented support for
+    character arrays and arrays of strings (e.g. ``character*(*) a(m,..)``).
+    *Important bug fixes regarding complex arguments, upgrading is
+    highly recommended*. Documentation updates.
+    `Differences with the previous release (version 2.37.233-1545)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.83&r2=1.58&f=h
+
+  September 11, 2003
+    Latest F2PY release (version 2.37.233-1545).
+    New statements: ``pymethoddef`` and ``usercode`` in interface blocks.
+    New function: ``as_column_major_storage``.
+    New CPP macro: ``F2PY_REPORT_ON_ARRAY_COPY``.
+    Bug fixes.
+    `Differences with the previous release (version 2.35.229-1505)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.58&r2=1.49&f=h
+
+  August 2, 2003
+    Latest F2PY release (version 2.35.229-1505).
+    `Differences with the previous release (version 2.32.225-1419)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.49&r2=1.28&f=h
+
+  April 2, 2003
+    Initial support for Numarray_ (thanks to Todd Miller).
+
+  December 8, 2002
+    Sixth public release of F2PY (version 2.32.225-1419). Comes with
+    revised `F2PY Users Guide`__, `new testing site`__, lots of fixes
+    and other improvements, see `HISTORY.txt`_ for details.
+
+  __ usersguide/index.html
+  __ TESTING.txt_
+
+.. References
+   ==========
+
+.. _HISTORY.txt: HISTORY.html
+.. _Numarray: http://www.stsci.edu/resources/software_hardware/numarray
+.. _TESTING.txt: TESTING.html
\ No newline at end of file
diff --git a/numpy/f2py/docs/README.txt b/numpy/f2py/docs/README.txt
new file mode 100644
index 000000000..fc7149645
--- /dev/null
+++ b/numpy/f2py/docs/README.txt
@@ -0,0 +1,457 @@
+.. -*- rest -*-
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ F2PY: Fortran to Python interface generator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Author: Pearu Peterson <pearu@cens.ioc.ee>
+:License: LGPL_.
+:Web-site: http://cens.ioc.ee/projects/f2py2e/
+:Discussions to: `f2py-users mailing list`_
+:Documentation: `User's Guide`__, FAQ__
+:Platforms: All
+:Date: $Date: 2005/01/30 18:54:53 $
+
+.. _f2py-users mailing list: http://cens.ioc.ee/mailman/listinfo/f2py-users/
+__ usersguide/index.html
+__ FAQ.html
+
+-------------------------------
+
+.. topic:: NEWS!!!
+
+  January 30, 2005
+
+    Latest F2PY release (version 2.45.241_1926).
+    New features: wrapping unsigned integers, support for ``.pyf.src`` template files,
+    callback arguments can now be CObjects, fortran objects, built-in functions.
+    Introduced ``intent(aux)`` attribute. Wrapped objects have ``_cpointer``
+    attribute holding C pointer to wrapped functions or variables.
+    Many bug fixes and improvements, updated documentation.
+    `Differences with the previous release (version 2.43.239_1831)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.163&r2=1.137&f=h
+
+  October 4, 2004
+    F2PY bug fix release (version 2.43.239_1831).
+    Better support for 64-bit platforms.
+    Introduced ``--help-link`` and ``--link-<resource>`` options.
+    Bug fixes.
+    `Differences with the previous release (version 2.43.239_1806)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.137&r2=1.131&f=h
+
+  September 25, 2004
+    Latest F2PY release (version 2.43.239_1806). 
+    Support for ``ENTRY`` statement. New attributes:
+    ``intent(inplace)``, ``intent(callback)``. Supports Numarray 1.1.
+    Introduced ``-*- fix -*-`` header content. Improved ``PARAMETER`` support.
+    Documentation updates. `Differences with the previous release
+    (version 2.39.235-1693)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.131&r2=1.98&f=h
+
+  `History of NEWS`__
+
+  __ OLDNEWS.html
+
+-------------------------------
+
+.. Contents::
+
+==============
+ Introduction
+==============
+
+The purpose of the F2PY --*Fortran to Python interface generator*--
+project is to provide connection between Python_ and Fortran
+languages. F2PY is a Python extension tool for creating Python C/API
+modules from (handwritten or F2PY generated) signature files (or
+directly from Fortran sources). The generated extension modules
+facilitate:
+
+* Calling Fortran 77/90/95, Fortran 90/95 module, and C functions from
+  Python.
+
+* Accessing Fortran 77 ``COMMON`` blocks and Fortran 90/95 module
+  data (including allocatable arrays) from Python.
+
+* Calling Python functions from Fortran or C (call-backs).
+
+* Automatically handling the difference in the data storage order of
+  multi-dimensional Fortran and Numerical Python (i.e. C) arrays.
+
+In addition, F2PY can build the generated extension modules to shared
+libraries with one command. F2PY uses the ``scipy_distutils`` module
+from SciPy_ that supports number of major Fortran compilers.
+
+..
+  (see `COMPILERS.txt`_ for more information).
+
+F2PY generated extension modules depend on NumPy_ package that
+provides fast multi-dimensional array language facility to Python.
+
+
+---------------
+ Main features
+---------------
+
+Here follows a more detailed list of F2PY features:
+
+* F2PY scans real Fortran codes to produce the so-called signature
+  files (.pyf files). The signature files contain all the information
+  (function names, arguments and their types, etc.)  that is needed to
+  construct Python bindings to Fortran (or C) functions.
+
+  The syntax of signature files is borrowed from the
+  Fortran 90/95 language specification and has some F2PY specific
+  extensions. The signature files can be modified to dictate how
+  Fortran (or C) programs are called from Python:
+
+    + F2PY solves dependencies between arguments (this is relevant for
+      the order of initializing variables in extension modules).
+
+    + Arguments can be specified to be optional or hidden that
+      simplifies calling Fortran programs from Python considerably.
+
+    + In principle, one can design any Python signature for a given
+      Fortran function, e.g. change the order arguments, introduce
+      auxiliary arguments, hide the arguments, process the arguments
+      before passing to Fortran, return arguments as output of F2PY
+      generated functions, etc.
+
+* F2PY automatically generates __doc__ strings (and optionally LaTeX
+  documentation) for extension modules.
+
+* F2PY generated functions accept arbitrary (but sensible) Python
+  objects as arguments. The F2PY interface automatically takes care of
+  type-casting and handling of non-contiguous arrays.
+
+* The following Fortran constructs are recognized by F2PY:
+
+  + All basic Fortran types::
+
+      integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ]
+      integer*([ -1 | -2 | -4 | -8 ])
+      character[ | *(*) | *1 | *2 | *3 | ... ]
+      real[ | *4 | *8 | *16 ], double precision
+      complex[ | *8 | *16 | *32 ]
+
+    Negative ``integer`` kinds are used to wrap unsigned integers.
+
+  + Multi-dimensional arrays of all basic types with the following
+    dimension specifications::
+
+      <dim> | <start>:<end> | * | :
+
+  + Attributes and statements::
+     
+      intent([ in | inout | out | hide | in,out | inout,out | c |
+               copy | cache | callback | inplace | aux ])
+      dimension(<dimspec>)
+      common, parameter
+      allocatable
+      optional, required, external
+      depend([<names>])
+      check([<C-booleanexpr>])
+      note(<LaTeX text>)
+      usercode, callstatement, callprotoargument, threadsafe, fortranname
+      pymethoddef
+      entry
+
+* Because there are only little (and easily handleable) differences
+  between calling C and Fortran functions from F2PY generated
+  extension modules, then F2PY is also well suited for wrapping C
+  libraries to Python.
+
+* Practice has shown that F2PY generated interfaces (to C or Fortran
+  functions) are less error prone and even more efficient than
+  handwritten extension modules. The F2PY generated interfaces are
+  easy to maintain and any future optimization of F2PY generated
+  interfaces transparently apply to extension modules by just
+  regenerating them with the latest version of F2PY.
+
+* `F2PY Users Guide and Reference Manual`_
+
+
+===============
+ Prerequisites
+===============
+
+F2PY requires the following software installed:
+
+* Python_ (versions 1.5.2 or later; 2.1 and up are recommended).
+  You must have python-dev package installed.
+* NumPy_ (versions 13 or later; 20.x, 21.x, 22.x, 23.x are recommended)
+* Numarray_ (version 0.9 and up), optional, partial support.
+* Scipy_distutils (version 0.2.2 and up are recommended) from SciPy_
+  project. Get it from Scipy CVS or download it below.
+
+Python 1.x users also need distutils_.
+
+Of course, to build extension modules, you'll need also working C
+and/or Fortran compilers installed.
+
+==========
+ Download
+==========
+
+You can download the sources for the latest F2PY and scipy_distutils
+releases as:
+
+* `2.x`__/`F2PY-2-latest.tar.gz`__
+* `2.x`__/`scipy_distutils-latest.tar.gz`__
+
+Windows users might be interested in Win32 installer for F2PY and
+Scipy_distutils (these installers are built using Python 2.3):
+
+* `2.x`__/`F2PY-2-latest.win32.exe`__
+* `2.x`__/`scipy_distutils-latest.win32.exe`__
+
+Older releases are also available in the directories
+`rel-0.x`__, `rel-1.x`__, `rel-2.x`__, `rel-3.x`__, `rel-4.x`__, `rel-5.x`__,
+if you need them.
+
+.. __: 2.x/
+.. __: 2.x/F2PY-2-latest.tar.gz
+.. __: 2.x/
+.. __: 2.x/scipy_distutils-latest.tar.gz
+.. __: 2.x/
+.. __: 2.x/F2PY-2-latest.win32.exe
+.. __: 2.x/
+.. __: 2.x/scipy_distutils-latest.win32.exe
+.. __: rel-0.x
+.. __: rel-1.x
+.. __: rel-2.x
+.. __: rel-3.x
+.. __: rel-4.x
+.. __: rel-5.x
+
+Development version of F2PY from CVS is available as `f2py2e.tar.gz`__.
+
+__ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/f2py2e.tar.gz?tarball=1
+
+Debian Sid users can simply install ``python-f2py`` package.
+
+==============
+ Installation
+==============
+
+Unpack the source file, change to directrory ``F2PY-?-???/`` and run
+(you may need to become a root)::
+
+  python setup.py install
+
+The F2PY installation installs a Python package ``f2py2e`` to your
+Python ``site-packages`` directory and a script ``f2py`` to your
+Python executable path. 
+
+See also Installation__ section in `F2PY FAQ`_.
+
+.. __: FAQ.html#installation
+
+Similarly, to install ``scipy_distutils``, unpack its tar-ball and run::
+
+  python setup.py install
+
+=======
+ Usage
+=======
+
+To check if F2PY is installed correctly, run
+::
+
+  f2py
+
+without any arguments. This should print out the usage information of
+the ``f2py`` program.
+
+Next, try out the following three steps:
+
+1) Create a Fortran file `hello.f`__ that contains::
+
+    C File hello.f
+          subroutine foo (a)
+          integer a
+          print*, "Hello from Fortran!"
+          print*, "a=",a
+          end
+
+__ hello.f
+
+2) Run
+
+  ::
+  
+    f2py -c -m hello hello.f
+
+  This will build an extension module ``hello.so`` (or ``hello.sl``,
+  or ``hello.pyd``, etc. depending on your platform) into the current
+  directory.
+
+3) Now in Python try::
+
+    >>> import hello
+    >>> print hello.__doc__
+    >>> print hello.foo.__doc__
+    >>> hello.foo(4)     
+     Hello from Fortran!
+     a= 4
+    >>> 
+
+If the above works, then you can try out more thorough 
+`F2PY unit tests`__ and read the `F2PY Users Guide and Reference Manual`_.
+
+__ FAQ.html#q-how-to-test-if-f2py-is-working-correctly
+
+===============
+ Documentation
+===============
+
+The documentation of the F2PY project is collected in ``f2py2e/docs/``
+directory. It contains the following documents:
+
+`README.txt`_ (in CVS__)
+  The first thing to read about F2PY -- this document.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/README.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`usersguide/index.txt`_, `usersguide/f2py_usersguide.pdf`_
+  F2PY Users Guide and Reference Manual. Contains lots of examples.
+
+`FAQ.txt`_ (in CVS__)
+  F2PY Frequently Asked Questions.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/FAQ.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`TESTING.txt`_ (in CVS__)
+  About F2PY testing site. What tests are available and how to run them.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/TESTING.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`HISTORY.txt`_ (in CVS__)
+  A list of latest changes in F2PY. This is the most up-to-date
+  document on F2PY.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`THANKS.txt`_
+  Acknowledgments.
+
+..
+  `COMPILERS.txt`_
+  Compiler and platform specific notes.
+
+===============
+ Mailing list
+===============
+
+A mailing list f2py-users@cens.ioc.ee is open for F2PY releated
+discussion/questions/etc.
+
+* `Subscribe..`__ 
+* `Archives..`__
+
+__ http://cens.ioc.ee/mailman/listinfo/f2py-users
+__ http://cens.ioc.ee/pipermail/f2py-users
+
+
+=====
+ CVS
+=====
+
+F2PY is being developed under CVS_. The CVS version of F2PY can be
+obtained as follows:
+
+1) First you need to login (the password is ``guest``)::
+
+    cvs -d :pserver:anonymous@cens.ioc.ee:/home/cvs login
+
+2) and then do the checkout::
+
+    cvs -z6 -d :pserver:anonymous@cens.ioc.ee:/home/cvs checkout f2py2e
+
+3) You can update your local F2PY tree ``f2py2e/`` by executing::
+
+    cvs -z6 update -P -d
+
+You can browse the `F2PY CVS`_ repository.
+
+===============
+ Contributions
+===============
+
+* `A short introduction to F2PY`__ by Pierre Schnizer.
+
+* `F2PY notes`__ by Fernando Perez.
+
+* `Debian packages of F2PY`__ by José Fonseca. [OBSOLETE, Debian Sid
+  ships python-f2py package]
+
+__ http://fubphpc.tu-graz.ac.at/~pierre/f2py_tutorial.tar.gz
+__ http://cens.ioc.ee/pipermail/f2py-users/2003-April/000472.html
+__ http://jrfonseca.dyndns.org/debian/
+
+
+===============
+ Related sites
+===============
+
+* `Numerical Python`_ -- adds a fast array facility to the Python language.
+* Pyfort_ -- A Python-Fortran connection tool.
+* SciPy_ -- An open source library of scientific tools for Python.
+* `Scientific Python`_ -- A collection of Python modules that are
+  useful for scientific computing.
+* `The Fortran Company`_ -- A place to find products, services, and general
+  information related to the Fortran programming language.
+* `American National Standard Programming Language FORTRAN ANSI(R) X3.9-1978`__
+* `J3`_ -- The US Fortran standards committee.
+* SWIG_ -- A software development tool that connects programs written
+  in C and C++ with a variety of high-level programming languages. 
+* `Mathtools.net`_ -- A technical computing portal for all scientific
+  and engineering needs. 
+
+.. __: http://www.fortran.com/fortran/F77_std/rjcnf.html
+
+.. References
+   ==========
+
+
+.. _F2PY Users Guide and Reference Manual: usersguide/index.html
+.. _usersguide/index.txt: usersguide/index.html
+.. _usersguide/f2py_usersguide.pdf: usersguide/f2py_usersguide.pdf
+.. _README.txt: README.html
+.. _COMPILERS.txt: COMPILERS.html
+.. _F2PY FAQ:
+.. _FAQ.txt: FAQ.html
+.. _HISTORY.txt: HISTORY.html
+.. _HISTORY.txt from CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+.. _THANKS.txt: THANKS.html
+.. _TESTING.txt: TESTING.html
+.. _F2PY CVS2: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/
+.. _F2PY CVS: http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/
+
+.. _CVS: http://www.cvshome.org/
+.. _Python: http://www.python.org/
+.. _SciPy: http://www.scipy.org/
+.. _NumPy: http://www.numpy.org/
+.. _Numarray: http://www.stsci.edu/resources/software_hardware/numarray
+.. _docutils: http://docutils.sourceforge.net/
+.. _distutils: http://www.python.org/sigs/distutils-sig/
+.. _LGPL: http://www.fsf.org/copyleft/lesser.html
+.. _Numerical Python: http://www.numpy.org/
+.. _Pyfort: http://pyfortran.sourceforge.net/
+.. _Scientific Python: 
+   http://starship.python.net/crew/hinsen/scientific.html
+.. _The Fortran Company: http://www.fortran.com/fortran/
+.. _J3: http://www.j3-fortran.org/
+.. _Mathtools.net: http://www.mathtools.net/
+.. _SWIG: http://www.swig.org/
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
diff --git a/numpy/f2py/docs/TESTING.txt b/numpy/f2py/docs/TESTING.txt
new file mode 100644
index 000000000..feae18dc6
--- /dev/null
+++ b/numpy/f2py/docs/TESTING.txt
@@ -0,0 +1,108 @@
+
+=======================================================
+                  F2PY unit testing site
+=======================================================
+
+.. Contents::
+
+Tests
+-----
+
+* To run all F2PY unit tests in one command::
+
+    cd tests
+    python run_all.py [<options>]
+
+  For example::
+
+    localhost:~/src_cvs/f2py2e/tests$ python2.2 run_all.py 100 --quiet
+    **********************************************
+    Running '/usr/bin/python2.2 f77/return_integer.py 100 --quiet'
+    run 1000 tests in 1.87 seconds
+    initial virtual memory size: 3952640 bytes
+    current virtual memory size: 3952640 bytes
+    ok
+    **********************************************
+    Running '/usr/bin/python2.2 f77/return_logical.py 100 --quiet'
+    run 1000 tests in 1.47 seconds
+    initial virtual memory size: 3952640 bytes
+    current virtual memory size: 3952640 bytes
+    ok
+    ...
+
+  If some tests fail, try to run the failing tests separately (without
+  the ``--quiet`` option) as described below to get more information
+  about the failure.
+
+* Test intent(in), intent(out) scalar arguments,
+  scalars returned by F77 functions 
+  and F90 module functions::
+
+    tests/f77/return_integer.py
+    tests/f77/return_real.py
+    tests/f77/return_logical.py
+    tests/f77/return_complex.py
+    tests/f77/return_character.py
+    tests/f90/return_integer.py
+    tests/f90/return_real.py
+    tests/f90/return_logical.py
+    tests/f90/return_complex.py
+    tests/f90/return_character.py
+
+  Change to tests/ directory and run::
+
+    python f77/return_<type>.py [<options>]
+    python f90/return_<type>.py [<options>]
+
+  where ``<type>`` is integer, real, logical, complex, or character.
+  Test scripts options are described below.
+
+  A test is considered succesful if the last printed line is "ok".
+
+  If you get import errors like::
+
+    ImportError: No module named f77_ext_return_integer
+
+  but ``f77_ext_return_integer.so`` exists in the current directory then
+  it means that the current directory is not included in to `sys.path`
+  in your Python installation. As a fix, prepend ``.`` to ``PYTHONPATH``
+  environment variable and rerun the tests. For example::
+
+    PYTHONPATH=. python f77/return_integer.py
+
+* Test mixing Fortran 77, Fortran 90 fixed and free format codes::
+
+    tests/mixed/run.py
+
+* Test basic callback hooks::
+
+    tests/f77/callback.py
+
+Options
+-------
+
+You may want to use the following options when running the test
+scripts:
+
+``<integer>``
+  Run tests ``<integer>`` times. Useful for detecting memory leaks.  Under
+  Linux tests scripts output virtual memory size state of the process
+  before and after calling the wrapped functions.
+
+``--quiet``
+  Suppress all messages. On success only "ok" should be displayed.
+
+``--fcompiler=<Gnu|Intel|...>``
+  Use::
+
+    f2py -c --help-fcompiler
+
+  to find out what compilers are available (or more precisely, which
+  ones are recognized by ``scipy_distutils``).
+
+Reporting failures
+------------------
+
+XXX: (1) make sure that failures are due to f2py and (2) send full
+stdout/stderr messages to me. Also add compiler,python,platform
+information.
diff --git a/numpy/f2py/docs/THANKS.txt b/numpy/f2py/docs/THANKS.txt
new file mode 100644
index 000000000..cbaa083fc
--- /dev/null
+++ b/numpy/f2py/docs/THANKS.txt
@@ -0,0 +1,63 @@
+
+=================
+ Acknowledgments
+=================
+
+F2PY__ is a LGPL'd Python package and command line tool developed and
+maintained by Pearu Peterson (me__). 
+
+.. __: http://cens.ioc.ee/projects/f2py2e/
+.. __: http://cens.ioc.ee/~pearu/
+
+Many people have contributed to the F2PY project in terms of interest,
+encouragement, suggestions, criticism, bug reports, code
+contributions, and keeping me busy with developing F2PY. For all that
+I thank
+
+  James Amundson, John Barnard, David Beazley, Frank Bertoldi, Roman
+  Bertle, James Boyle, Moritz Braun, Rolv Erlend Bredesen, John
+  Chaffer, Fred Clare, Adam Collard, Ben Cornett, Jose L Gomez Dans,
+  Jaime D. Perea Duarte, Paul F Dubois, Thilo Ernst, Bonilla Fabian,
+  Martin Gelfand, Eduardo A. Gonzalez, Siegfried Gonzi, Bernhard
+  Gschaider, Charles Doutriaux, Jeff Hagelberg, Janko Hauser, Thomas
+  Hauser, Heiko Henkelmann, William Henney, Yueqiang Huang, Asim
+  Hussain, Berthold Höllmann, Vladimir Janku, Henk Jansen, Curtis
+  Jensen, Eric Jones, Tiffany Kamm, Andrey Khavryuchenko, Greg
+  Kochanski, Jochen Küpper, Simon Lacoste-Julien, Tim Lahey, Hans
+  Petter Langtangen, Jeff Layton, Matthew Lewis, Patrick LeGresley,
+  Joaquim R R A Martins, Paul Magwene Lionel Maziere, Craig McNeile,
+  Todd Miller, David C. Morrill, Dirk Muders, Kevin Mueller, Andrew
+  Mullhaupt, Vijayendra Munikoti, Travis Oliphant, Kevin O'Mara, Arno
+  Paehler, Fernando Perez, Didrik Pinte, Todd Alan Pitts, Prabhu
+  Ramachandran, Brad Reisfeld, Steve M. Robbins, Theresa Robinson,
+  Pedro Rodrigues, Les Schaffer, Christoph Scheurer, Herb Schilling,
+  Pierre Schnizer, Kevin Smith, Paulo Teotonio Sobrinho, José Rui
+  Faustino de Sousa, Andrew Swan, Dustin Tang, Charlie Taylor, Paul le
+  Texier, Michael Tiller, Semen Trygubenko, Ravi C Venkatesan, Peter
+  Verveer, Nils Wagner, R. Clint Whaley, Erik Wilsher, Martin
+  Wiechert, Gilles Zerah, SungPil Yoon.
+
+(This list may not be complete. Please forgive me if I have left you
+out and let me know, I'll add your name.)
+
+Special thanks are due to ...
+
+Eric Jones - he and Travis O. are responsible for starting the
+scipy_distutils project that allowed to move most of the platform and
+compiler specific codes out from F2PY. This simplified maintaining the
+F2PY project considerably.
+
+Joaquim R R A Martins - he made possible for me to test F2PY on IRIX64
+platform. He also presented our paper about F2PY in the 9th Python
+Conference that I planned to attend but had to cancel in very last
+minutes.
+
+Travis Oliphant - his knowledge and experience on Numerical Python
+C/API has been invaluable in early development of the F2PY program.
+His major contributions are call-back mechanism and copying N-D arrays
+of arbitrary types.
+
+Todd Miller - he is responsible for Numarray support in F2PY.
+
+Thanks!
+	Pearu
diff --git a/numpy/f2py/docs/default.css b/numpy/f2py/docs/default.css
new file mode 100644
index 000000000..9289e2826
--- /dev/null
+++ b/numpy/f2py/docs/default.css
@@ -0,0 +1,180 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date: 2002/08/01 20:52:44 $
+:version: $Revision: 1.1 $
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+
+body {
+  background: #FFFFFF ;
+  color: #000000
+}
+
+a.footnote-reference {
+  font-size: smaller ;
+  vertical-align: super }
+
+a.target {
+  color: blue }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+dd {
+  margin-bottom: 0.5em }
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em }
+
+div.footer, div.header {
+  font-size: smaller }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr {
+  width: 75% }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.first {
+  margin-top: 0 }
+
+p.label {
+  white-space: nowrap }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em ;
+  background-color: #eeeeee }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.field-argument {
+  font-style: italic }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option-argument {
+  font-style: italic }
+
+span.problematic {
+  color: red }
+
+table {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.citation {
+  border-left: solid thin gray ;
+  padding-left: 0.5ex }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.footnote {
+  border-left: solid thin black ;
+  padding-left: 0.5ex }
+
+td, th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: baseline }
+
+td.docinfo-name {
+  font-weight: bold ;
+  text-align: right }
+
+td.field-name {
+  font-weight: bold }
diff --git a/numpy/f2py/docs/docutils.conf b/numpy/f2py/docs/docutils.conf
new file mode 100644
index 000000000..4e5a8425b
--- /dev/null
+++ b/numpy/f2py/docs/docutils.conf
@@ -0,0 +1,16 @@
+[general]
+
+# These entries affect all processing:
+#source-link: 1
+datestamp: %Y-%m-%d %H:%M UTC
+generator: 1
+
+# These entries affect HTML output:
+#stylesheet-path: pearu_style.css
+output-encoding: latin-1
+
+# These entries affect reStructuredText-style PEPs:
+#pep-template: pep-html-template
+#pep-stylesheet-path: stylesheets/pep.css
+#python-home: http://www.python.org
+#no-random: 1
diff --git a/numpy/f2py/docs/hello.f b/numpy/f2py/docs/hello.f
new file mode 100644
index 000000000..3e0dc6d21
--- /dev/null
+++ b/numpy/f2py/docs/hello.f
@@ -0,0 +1,7 @@
+C File hello.f
+      subroutine foo (a)
+      integer a
+      print*, "Hello from Fortran!"
+      print*, "a=",a
+      end
+
diff --git a/numpy/f2py/docs/pyforttest.pyf b/numpy/f2py/docs/pyforttest.pyf
new file mode 100644
index 000000000..79a9ae205
--- /dev/null
+++ b/numpy/f2py/docs/pyforttest.pyf
@@ -0,0 +1,5 @@
+subroutine foo(a,m,n)
+integer m = size(a,1)
+integer n = size(a,2)
+real, intent(inout) :: a(m,n)
+end subroutine foo
diff --git a/numpy/f2py/docs/pytest.py b/numpy/f2py/docs/pytest.py
new file mode 100644
index 000000000..abd3487df
--- /dev/null
+++ b/numpy/f2py/docs/pytest.py
@@ -0,0 +1,10 @@
+#File: pytest.py
+import Numeric
+def foo(a):
+    a = Numeric.array(a)
+    m,n = a.shape
+    for i in range(m):
+        for j in range(n):
+            a[i,j] = a[i,j] + 10*(i+1) + (j+1)
+    return a
+#eof
diff --git a/numpy/f2py/docs/simple.f b/numpy/f2py/docs/simple.f
new file mode 100644
index 000000000..ba468a509
--- /dev/null
+++ b/numpy/f2py/docs/simple.f
@@ -0,0 +1,13 @@
+cFile: simple.f
+      subroutine foo(a,m,n)
+      integer m,n,i,j
+      real a(m,n)
+cf2py intent(in,out) a
+cf2py intent(hide) m,n
+      do i=1,m
+         do j=1,n
+            a(i,j) = a(i,j) + 10*i+j
+         enddo
+      enddo
+      end
+cEOF
diff --git a/numpy/f2py/docs/simple_session.dat b/numpy/f2py/docs/simple_session.dat
new file mode 100644
index 000000000..10d9dc962
--- /dev/null
+++ b/numpy/f2py/docs/simple_session.dat
@@ -0,0 +1,51 @@
+>>> import pytest
+>>> import f2pytest
+>>> import pyforttest
+>>> print f2pytest.foo.__doc__
+foo - Function signature:
+  a = foo(a)
+Required arguments:
+  a : input rank-2 array('f') with bounds (m,n)
+Return objects:
+  a : rank-2 array('f') with bounds (m,n)
+
+>>> print pyforttest.foo.__doc__
+foo(a)
+
+>>> pytest.foo([[1,2],[3,4]])
+array([[12, 14],
+       [24, 26]])
+>>> f2pytest.foo([[1,2],[3,4]])  # F2PY can handle arbitrary input sequences
+array([[ 12.,  14.],
+       [ 24.,  26.]],'f')
+>>> pyforttest.foo([[1,2],[3,4]])
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+pyforttest.error: foo, argument A: Argument intent(inout) must be an array.
+
+>>> import Numeric
+>>> a=Numeric.array([[1,2],[3,4]],'f')
+>>> f2pytest.foo(a)
+array([[ 12.,  14.],
+       [ 24.,  26.]],'f')
+>>> a   # F2PY makes a copy when input array is not Fortran contiguous
+array([[ 1.,  2.],
+       [ 3.,  4.]],'f')
+>>> a=Numeric.transpose(Numeric.array([[1,3],[2,4]],'f'))
+>>> a
+array([[ 1.,  2.],
+       [ 3.,  4.]],'f')
+>>> f2pytest.foo(a)
+array([[ 12.,  14.],
+       [ 24.,  26.]],'f')
+>>> a   # F2PY passes Fortran contiguous input array directly to Fortran
+array([[ 12.,  14.],
+       [ 24.,  26.]],'f')
+# See intent(copy), intent(overwrite), intent(inplace), intent(inout)
+# attributes documentation to enhance the above behavior.
+
+>>> a=Numeric.array([[1,2],[3,4]],'f')
+>>> pyforttest.foo(a)
+>>> a   # Huh? Pyfort 8.5 gives wrong results..
+array([[ 12.,  23.],
+       [ 15.,  26.]],'f')
diff --git a/numpy/f2py/docs/usersguide/allocarr.f90 b/numpy/f2py/docs/usersguide/allocarr.f90
new file mode 100644
index 000000000..e0d6c2ec8
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/allocarr.f90
@@ -0,0 +1,16 @@
+module mod
+  real, allocatable, dimension(:,:) :: b 
+contains
+  subroutine foo
+    integer k
+    if (allocated(b)) then
+       print*, "b=["
+       do k = 1,size(b,1)
+          print*, b(k,1:size(b,2))
+       enddo
+       print*, "]"
+    else
+       print*, "b is not allocated"
+    endif
+  end subroutine foo
+end module mod
diff --git a/numpy/f2py/docs/usersguide/allocarr_session.dat b/numpy/f2py/docs/usersguide/allocarr_session.dat
new file mode 100644
index 000000000..fc91959b7
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/allocarr_session.dat
@@ -0,0 +1,27 @@
+>>> import allocarr 
+>>> print allocarr.mod.__doc__
+b - 'f'-array(-1,-1), not allocated
+foo - Function signature:
+  foo()
+
+>>> allocarr.mod.foo()  
+ b is not allocated
+>>> allocarr.mod.b = [[1,2,3],[4,5,6]]         # allocate/initialize b
+>>> allocarr.mod.foo()
+ b=[
+   1.000000       2.000000       3.000000    
+   4.000000       5.000000       6.000000    
+ ]
+>>> allocarr.mod.b                             # b is Fortran-contiguous
+array([[ 1.,  2.,  3.],
+       [ 4.,  5.,  6.]],'f')
+>>> allocarr.mod.b = [[1,2,3],[4,5,6],[7,8,9]] # reallocate/initialize b
+>>> allocarr.mod.foo()
+ b=[
+   1.000000       2.000000       3.000000    
+   4.000000       5.000000       6.000000    
+   7.000000       8.000000       9.000000    
+ ]
+>>> allocarr.mod.b = None                      # deallocate array
+>>> allocarr.mod.foo()
+ b is not allocated
diff --git a/numpy/f2py/docs/usersguide/array.f b/numpy/f2py/docs/usersguide/array.f
new file mode 100644
index 000000000..ef20c9c20
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/array.f
@@ -0,0 +1,17 @@
+C FILE: ARRAY.F
+      SUBROUTINE FOO(A,N,M)
+C
+C     INCREMENT THE FIRST ROW AND DECREMENT THE FIRST COLUMN OF A
+C
+      INTEGER N,M,I,J
+      REAL*8 A(N,M)
+Cf2py intent(in,out,copy) a
+Cf2py integer intent(hide),depend(a) :: n=shape(a,0), m=shape(a,1)
+      DO J=1,M
+         A(1,J) = A(1,J) + 1D0
+      ENDDO
+      DO I=1,N
+         A(I,1) = A(I,1) - 1D0
+      ENDDO
+      END
+C END OF FILE ARRAY.F
diff --git a/numpy/f2py/docs/usersguide/array_session.dat b/numpy/f2py/docs/usersguide/array_session.dat
new file mode 100644
index 000000000..f64933482
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/array_session.dat
@@ -0,0 +1,65 @@
+>>> import arr
+>>> from Numeric import array
+>>> print arr.foo.__doc__
+foo - Function signature:
+  a = foo(a,[overwrite_a])
+Required arguments:
+  a : input rank-2 array('d') with bounds (n,m)
+Optional arguments:
+  overwrite_a := 0 input int
+Return objects:
+  a : rank-2 array('d') with bounds (n,m)
+
+>>> a=arr.foo([[1,2,3],
+...            [4,5,6]])
+copied an array using PyArray_CopyFromObject: size=6, elsize=8
+>>> print a
+[[ 1.  3.  4.]
+ [ 3.  5.  6.]]
+>>> a.iscontiguous(), arr.has_column_major_storage(a)
+(0, 1)
+>>> b=arr.foo(a)              # even if a is proper-contiguous
+...                           # and has proper type, a copy is made
+...                           # forced by intent(copy) attribute
+...                           # to preserve its original contents
+... 
+copied an array using copy_ND_array: size=6, elsize=8
+>>> print a
+[[ 1.  3.  4.]
+ [ 3.  5.  6.]]
+>>> print b
+[[ 1.  4.  5.]
+ [ 2.  5.  6.]]
+>>> b=arr.foo(a,overwrite_a=1) # a is passed directly to Fortran
+...                            # routine and its contents is discarded
+... 
+>>> print a
+[[ 1.  4.  5.]
+ [ 2.  5.  6.]]
+>>> print b
+[[ 1.  4.  5.]
+ [ 2.  5.  6.]]
+>>> a is b                       # a and b are acctually the same objects
+1
+>>> print arr.foo([1,2,3])       # different rank arrays are allowed
+copied an array using PyArray_CopyFromObject: size=3, elsize=8
+[ 1.  1.  2.]
+>>> print arr.foo([[[1],[2],[3]]])
+copied an array using PyArray_CopyFromObject: size=3, elsize=8
+[ [[ 1.]
+  [ 3.]
+  [ 4.]]]
+>>>
+>>> # Creating arrays with column major data storage order:
+...
+>>> s = arr.as_column_major_storage(array([[1,2,3],[4,5,6]]))
+copied an array using copy_ND_array: size=6, elsize=4
+>>> arr.has_column_major_storage(s)
+1
+>>> print s
+[[1 2 3]
+ [4 5 6]]
+>>> s2 = arr.as_column_major_storage(s)
+>>> s2 is s    # an array with column major storage order 
+               # is returned immediately
+1
\ No newline at end of file
diff --git a/numpy/f2py/docs/usersguide/calculate.f b/numpy/f2py/docs/usersguide/calculate.f
new file mode 100644
index 000000000..1cda1c8dd
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/calculate.f
@@ -0,0 +1,14 @@
+      subroutine calculate(x,n)
+cf2py intent(callback) func
+      external func
+c     The following lines define the signature of func for F2PY:
+cf2py real*8 y
+cf2py y = func(y)
+c
+cf2py intent(in,out,copy) x
+      integer n,i
+      real*8 x(n)
+      do i=1,n
+         x(i) = func(x(i))
+      end do
+      end
diff --git a/numpy/f2py/docs/usersguide/calculate_session.dat b/numpy/f2py/docs/usersguide/calculate_session.dat
new file mode 100644
index 000000000..2fe64f522
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/calculate_session.dat
@@ -0,0 +1,6 @@
+>>> import foo
+>>> foo.calculate(range(5), lambda x: x*x)
+array([  0.,   1.,   4.,   9.,  16.])
+>>> import math
+>>> foo.calculate(range(5), math.exp)
+array([  1.        ,   2.71828175,   7.38905621,  20.08553696,  54.59814835])
diff --git a/numpy/f2py/docs/usersguide/callback.f b/numpy/f2py/docs/usersguide/callback.f
new file mode 100644
index 000000000..6e9bfb920
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/callback.f
@@ -0,0 +1,12 @@
+C FILE: CALLBACK.F
+      SUBROUTINE FOO(FUN,R)
+      EXTERNAL FUN
+      INTEGER I
+      REAL*8 R
+Cf2py intent(out) r
+      R = 0D0
+      DO I=-5,5
+         R = R + FUN(I)
+      ENDDO
+      END
+C END OF FILE CALLBACK.F
diff --git a/numpy/f2py/docs/usersguide/callback2.pyf b/numpy/f2py/docs/usersguide/callback2.pyf
new file mode 100644
index 000000000..3d77eed24
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/callback2.pyf
@@ -0,0 +1,19 @@
+!    -*- f90 -*-
+python module __user__routines 
+    interface
+        function fun(i) result (r)
+            integer :: i
+            real*8 :: r
+        end function fun
+    end interface
+end python module __user__routines
+
+python module callback2
+    interface
+        subroutine foo(f,r)
+            use __user__routines, f=>fun
+            external f
+            real*8 intent(out) :: r
+        end subroutine foo
+    end interface 
+end python module callback2
diff --git a/numpy/f2py/docs/usersguide/callback_session.dat b/numpy/f2py/docs/usersguide/callback_session.dat
new file mode 100644
index 000000000..cd2f26084
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/callback_session.dat
@@ -0,0 +1,23 @@
+>>> import callback
+>>> print callback.foo.__doc__
+foo - Function signature:
+  r = foo(fun,[fun_extra_args])
+Required arguments:
+  fun : call-back function
+Optional arguments:
+  fun_extra_args := () input tuple
+Return objects:
+  r : float
+Call-back functions:
+  def fun(i): return r
+  Required arguments:
+    i : input int
+  Return objects:
+    r : float
+
+>>> def f(i): return i*i
+... 
+>>> print callback.foo(f)     
+110.0
+>>> print callback.foo(lambda i:1)
+11.0
diff --git a/numpy/f2py/docs/usersguide/common.f b/numpy/f2py/docs/usersguide/common.f
new file mode 100644
index 000000000..b098ab20c
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/common.f
@@ -0,0 +1,13 @@
+C FILE: COMMON.F
+      SUBROUTINE FOO
+      INTEGER I,X
+      REAL A
+      COMMON /DATA/ I,X(4),A(2,3)
+      PRINT*, "I=",I
+      PRINT*, "X=[",X,"]"
+      PRINT*, "A=["
+      PRINT*, "[",A(1,1),",",A(1,2),",",A(1,3),"]"
+      PRINT*, "[",A(2,1),",",A(2,2),",",A(2,3),"]"
+      PRINT*, "]"
+      END
+C END OF COMMON.F
diff --git a/numpy/f2py/docs/usersguide/common_session.dat b/numpy/f2py/docs/usersguide/common_session.dat
new file mode 100644
index 000000000..846fdaa07
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/common_session.dat
@@ -0,0 +1,27 @@
+>>> import common
+>>> print common.data.__doc__
+i - 'i'-scalar
+x - 'i'-array(4)
+a - 'f'-array(2,3)
+
+>>> common.data.i = 5
+>>> common.data.x[1] = 2 
+>>> common.data.a = [[1,2,3],[4,5,6]]
+>>> common.foo()
+ I= 5
+ X=[ 0 2 0 0]
+ A=[
+ [  1.,  2.,  3.]
+ [  4.,  5.,  6.]
+ ]
+>>> common.data.a[1] = 45
+>>> common.foo()
+ I= 5
+ X=[ 0 2 0 0]
+ A=[
+ [  1.,  2.,  3.]
+ [  45.,  45.,  45.]
+ ]
+>>> common.data.a                 # a is Fortran-contiguous
+array([[  1.,   2.,   3.],
+       [ 45.,  45.,  45.]],'f')
diff --git a/numpy/f2py/docs/usersguide/compile_session.dat b/numpy/f2py/docs/usersguide/compile_session.dat
new file mode 100644
index 000000000..0d8408198
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/compile_session.dat
@@ -0,0 +1,11 @@
+>>> import f2py2e
+>>> fsource = '''
+...       subroutine foo
+...       print*, "Hello world!"
+...       end 
+... '''
+>>> f2py2e.compile(fsource,modulename='hello',verbose=0)
+0
+>>> import hello
+>>> hello.foo()
+ Hello world!
diff --git a/numpy/f2py/docs/usersguide/default.css b/numpy/f2py/docs/usersguide/default.css
new file mode 100644
index 000000000..bb7226161
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/default.css
@@ -0,0 +1,180 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date: 2002/12/07 23:59:33 $
+:version: $Revision: 1.2 $
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+
+body {
+  background: #FFFFFF ;
+  color: #000000
+}
+
+a.footnote-reference {
+  font-size: smaller ;
+  vertical-align: super }
+
+a.target {
+  color: blue }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+dd {
+  margin-bottom: 0.5em }
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em }
+
+div.footer, div.header {
+  font-size: smaller }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr {
+  width: 75% }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.first {
+  margin-top: 0 }
+
+p.label {
+  white-space: nowrap }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em ;
+  background-color: #ee9e9e }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.field-argument {
+  font-style: italic }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option-argument {
+  font-style: italic }
+
+span.problematic {
+  color: red }
+
+table {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.citation {
+  border-left: solid thin gray ;
+  padding-left: 0.5ex }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.footnote {
+  border-left: solid thin black ;
+  padding-left: 0.5ex }
+
+td, th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: baseline }
+
+td.docinfo-name {
+  font-weight: bold ;
+  text-align: right }
+
+td.field-name {
+  font-weight: bold }
diff --git a/numpy/f2py/docs/usersguide/docutils.conf b/numpy/f2py/docs/usersguide/docutils.conf
new file mode 100644
index 000000000..b772fd137
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/docutils.conf
@@ -0,0 +1,16 @@
+[general]
+
+# These entries affect all processing:
+#source-link: 1
+datestamp: %Y-%m-%d %H:%M UTC
+generator: 1
+
+# These entries affect HTML output:
+#stylesheet-path: f2py_style.css
+output-encoding: latin-1
+
+# These entries affect reStructuredText-style PEPs:
+#pep-template: pep-html-template
+#pep-stylesheet-path: stylesheets/pep.css
+#python-home: http://www.python.org
+#no-random: 1
diff --git a/numpy/f2py/docs/usersguide/extcallback.f b/numpy/f2py/docs/usersguide/extcallback.f
new file mode 100644
index 000000000..9a800628e
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/extcallback.f
@@ -0,0 +1,14 @@
+      subroutine f1()
+         print *, "in f1, calling f2 twice.."
+         call f2()
+         call f2()
+         return
+      end
+      
+      subroutine f2()
+cf2py    intent(callback, hide) fpy
+         external fpy
+         print *, "in f2, calling f2py.."
+         call fpy()
+         return
+      end
diff --git a/numpy/f2py/docs/usersguide/extcallback_session.dat b/numpy/f2py/docs/usersguide/extcallback_session.dat
new file mode 100644
index 000000000..c22935ea0
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/extcallback_session.dat
@@ -0,0 +1,19 @@
+>>> import pfromf
+>>> pfromf.f2()
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+pfromf.error: Callback fpy not defined (as an argument or module pfromf attribute).
+
+>>> def f(): print "python f"
+... 
+>>> pfromf.fpy = f
+>>> pfromf.f2()
+ in f2, calling f2py..
+python f
+>>> pfromf.f1()
+ in f1, calling f2 twice..
+ in f2, calling f2py..
+python f
+ in f2, calling f2py..
+python f
+>>> 
\ No newline at end of file
diff --git a/numpy/f2py/docs/usersguide/fib1.f b/numpy/f2py/docs/usersguide/fib1.f
new file mode 100644
index 000000000..cfbb1eea0
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/fib1.f
@@ -0,0 +1,18 @@
+C FILE: FIB1.F
+      SUBROUTINE FIB(A,N)
+C
+C     CALCULATE FIRST N FIBONACCI NUMBERS
+C
+      INTEGER N
+      REAL*8 A(N)
+      DO I=1,N
+         IF (I.EQ.1) THEN
+            A(I) = 0.0D0
+         ELSEIF (I.EQ.2) THEN
+            A(I) = 1.0D0
+         ELSE 
+            A(I) = A(I-1) + A(I-2)
+         ENDIF
+      ENDDO
+      END
+C END FILE FIB1.F
diff --git a/numpy/f2py/docs/usersguide/fib1.pyf b/numpy/f2py/docs/usersguide/fib1.pyf
new file mode 100644
index 000000000..3d6cc0a54
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/fib1.pyf
@@ -0,0 +1,12 @@
+!    -*- f90 -*-
+python module fib2 ! in 
+    interface  ! in :fib2
+        subroutine fib(a,n) ! in :fib2:fib1.f
+            real*8 dimension(n) :: a
+            integer optional,check(len(a)>=n),depend(a) :: n=len(a)
+        end subroutine fib
+    end interface 
+end python module fib2
+
+! This file was auto-generated with f2py (version:2.28.198-1366).
+! See http://cens.ioc.ee/projects/f2py2e/
diff --git a/numpy/f2py/docs/usersguide/fib2.pyf b/numpy/f2py/docs/usersguide/fib2.pyf
new file mode 100644
index 000000000..4a5ae29f1
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/fib2.pyf
@@ -0,0 +1,9 @@
+!    -*- f90 -*-
+python module fib2 
+    interface
+        subroutine fib(a,n)
+            real*8 dimension(n),intent(out),depend(n) :: a
+            integer intent(in) :: n
+        end subroutine fib
+    end interface 
+end python module fib2
diff --git a/numpy/f2py/docs/usersguide/fib3.f b/numpy/f2py/docs/usersguide/fib3.f
new file mode 100644
index 000000000..08b050cd2
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/fib3.f
@@ -0,0 +1,21 @@
+C FILE: FIB3.F
+      SUBROUTINE FIB(A,N)
+C
+C     CALCULATE FIRST N FIBONACCI NUMBERS
+C
+      INTEGER N
+      REAL*8 A(N)
+Cf2py intent(in) n
+Cf2py intent(out) a
+Cf2py depend(n) a
+      DO I=1,N
+         IF (I.EQ.1) THEN
+            A(I) = 0.0D0
+         ELSEIF (I.EQ.2) THEN
+            A(I) = 1.0D0
+         ELSE 
+            A(I) = A(I-1) + A(I-2)
+         ENDIF
+      ENDDO
+      END
+C END FILE FIB3.F
diff --git a/numpy/f2py/docs/usersguide/ftype.f b/numpy/f2py/docs/usersguide/ftype.f
new file mode 100644
index 000000000..cabbb9e2d
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/ftype.f
@@ -0,0 +1,9 @@
+C FILE: FTYPE.F
+      SUBROUTINE FOO(N)
+      INTEGER N
+Cf2py integer optional,intent(in) :: n = 13
+      REAL A,X
+      COMMON /DATA/ A,X(3)
+      PRINT*, "IN FOO: N=",N," A=",A," X=[",X(1),X(2),X(3),"]"
+      END
+C END OF FTYPE.F
diff --git a/numpy/f2py/docs/usersguide/ftype_session.dat b/numpy/f2py/docs/usersguide/ftype_session.dat
new file mode 100644
index 000000000..01f9febaf
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/ftype_session.dat
@@ -0,0 +1,21 @@
+>>> import ftype
+>>> print ftype.__doc__
+This module 'ftype' is auto-generated with f2py (version:2.28.198-1366).
+Functions:
+  foo(n=13)
+COMMON blocks:
+  /data/ a,x(3)
+.
+>>> type(ftype.foo),type(ftype.data)
+(<type 'fortran'>, <type 'fortran'>)
+>>> ftype.foo()
+ IN FOO: N= 13 A=  0. X=[  0.  0.  0.]
+>>> ftype.data.a = 3
+>>> ftype.data.x = [1,2,3]
+>>> ftype.foo()
+ IN FOO: N= 13 A=  3. X=[  1.  2.  3.]
+>>> ftype.data.x[1] = 45  
+>>> ftype.foo(24)
+ IN FOO: N= 24 A=  3. X=[  1.  45.  3.]
+>>> ftype.data.x
+array([  1.,  45.,   3.],'f')
diff --git a/numpy/f2py/docs/usersguide/index.txt b/numpy/f2py/docs/usersguide/index.txt
new file mode 100644
index 000000000..9fafb99fb
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/index.txt
@@ -0,0 +1,1772 @@
+.. -*- rest -*-
+
+//////////////////////////////////////////////////////////////////////
+                  F2PY Users Guide and Reference Manual
+//////////////////////////////////////////////////////////////////////
+
+:Author: Pearu Peterson 
+:Contact: pearu@cens.ioc.ee
+:Web site: http://cens.ioc.ee/projects/f2py2e/
+:Date: $Date: 2005/04/02 10:03:26 $
+:Revision: $Revision: 1.27 $
+
+
+.. section-numbering::
+
+.. Contents::
+
+
+================
+ Introduction
+================
+
+The purpose of the F2PY_ --*Fortran to Python interface generator*--
+project is to provide a connection between Python and Fortran
+languages.  F2PY is a Python_ package (with a command line tool
+``f2py`` and a module ``f2py2e``) that facilitates creating/building
+Python C/API extension modules that make it possible
+
+* to call Fortran 77/90/95 external subroutines and Fortran 90/95
+  module subroutines as well as C functions;
+* to access Fortran 77 ``COMMON`` blocks and Fortran 90/95 module data,
+  including allocatable arrays
+
+from Python. See F2PY_ web site for more information and installation
+instructions.
+
+======================================
+ Three ways to wrap - getting started
+======================================
+
+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
+  signature file by scanning Fortran source codes and
+  catching 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".
+
+* 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
+  ``scipy_distutils`` that supports a number of Fortran 77/90/95
+  compilers, including Gnu, Intel,
+  Sun Fortre, SGI MIPSpro, Absoft, NAG, Compaq etc. compilers.
+
+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
+ommited or combined with others.
+
+Below I'll describe three typical approaches of using F2PY.
+The following `example Fortran 77 code`__ will be used for
+illustration:
+
+.. include:: fib1.f
+   :literal:
+
+__ fib1.f
+
+The quick way
+==============
+
+The quickest way to wrap the Fortran subroutine ``FIB`` to Python is
+to run
+
+::
+
+  f2py -c fib1.f -m fib1
+
+This command builds (see ``-c`` flag, execute ``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``::
+
+  >>> import Numeric
+  >>> import fib1
+  >>> print fib1.fib.__doc__
+  fib - Function signature:
+    fib(a,[n])
+  Required arguments:
+    a : input rank-1 array('d') with bounds (n)
+  Optional arguments:
+    n := len(a) input int
+  
+  >>> a=Numeric.zeros(8,'d')
+  >>> fib1.fib(a)
+  >>> print a
+  [  0.   1.   1.   2.   3.   5.   8.  13.]
+
+.. topic:: Comments
+
+  * Note that F2PY found 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=Numeric.zeros(8,'d')
+      >>> fib1.fib(a1,6)
+      >>> print a1
+      [ 0.  1.  1.  2.  3.  5.  0.  0.]
+
+    but an exception is raised when it is incompatible with the input
+    array ``a``::
+
+      >>> fib1.fib(a,10)
+      fib:n=10
+      Traceback (most recent call last):
+        File "<stdin>", line 1, in ?
+      fib.error: (len(a)>=n) failed for 1st keyword n
+      >>> 
+
+    This demonstrates one of the useful features in F2PY, that it,
+    F2PY implements basic compatibility checks between related
+    arguments in order to avoid any unexpected crashes.
+
+  * When a Numeric array, that is Fortran contiguous and has a typecode
+    corresponding to 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 typecode) of
+    the input array and passes C pointer of the copy to 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=Numeric.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 ``typecode='d'`` is considered
+    accidental.
+
+    F2PY provides ``intent(inplace)`` attribute that would modify
+    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:
+
+      >>> a=Numeric.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 acctual 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.
+
+The smart way
+==============
+
+Let's apply the steps of wrapping Fortran functions to Python one by
+one.
+
+* First, we create a signature file from ``fib1.f`` by running
+
+  ::
+
+    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.
+
+  .. include:: fib1.pyf
+     :literal:
+
+* Next, we'll teach F2PY that the argument ``n`` is a 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).
+
+  The content of a modified version of ``fib1.pyf`` (saved as
+  ``fib2.pyf``) is as follows:
+
+  .. include:: fib2.pyf
+     :literal:
+
+* And finally, we build the extension module by running
+
+  ::
+
+    f2py -c fib2.pyf fib1.f
+
+In Python::
+
+  >>> import fib2
+  >>> print fib2.fib.__doc__
+  fib - Function signature:
+    a = fib(n)
+  Required arguments:
+    n : input int
+  Return objects:
+    a : rank-1 array('d') with bounds (n)
+  
+  >>> print fib2.fib(8)     
+  [  0.   1.   1.   2.   3.   5.   8.  13.]
+
+.. topic:: Comments
+
+  * 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 Numeric array. Also, the new Python signature ``fib2.fib``
+    rules out any surprises that we experienced with ``fib1.fib``.
+
+  * Note that by default using single ``intent(out)`` also implies
+    ``intent(hide)``. Argument that has ``intent(hide)`` attribute
+    specified, will not be listed in the argument list of a wrapper
+    function.
+
+The quick and smart way
+========================
+
+The "smart way" of wrapping Fortran functions, as explained above, is
+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.
+
+Here is shown a `modified version of the example Fortran code`__, saved
+as ``fib3.f``:
+
+.. include:: fib3.f
+   :literal:
+
+__ fib3.f
+
+Building the extension module can be now carried out in one command::
+
+  f2py -c -m fib3 fib3.f
+
+Notice that the resulting wrapper to ``FIB`` is as "smart" as in
+previous case::
+
+  >>> import fib3
+  >>> print fib3.fib.__doc__
+  fib - Function signature:
+    a = fib(n)
+  Required arguments:
+    n : input int
+  Return objects:
+    a : rank-1 array('d') with bounds (n)
+  
+  >>> print fib3.fib(8)     
+  [  0.   1.   1.   2.   3.   5.   8.  13.]
+
+
+==================
+ 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
+Fortran constructs that are irrelevant for creating the interface.
+However, this includes also syntax errors. So, be careful not making
+ones;-).
+
+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 multi-line blocks or when ``--no-lower``
+option is used.
+
+The syntax of signature files is overvied below.
+
+Python module block
+=====================
+
+A signature file may contain one (recommended) or more ``python
+module`` blocks.  ``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 `Call-back arguments`_).
+
+A ``python module`` block has the following structure::
+
+  python module <modulename>
+    [<usercode statement>]...
+    [
+    interface
+      <usercode statement>
+      <Fortran block data signatures>
+      <Fortran/C routine signatures>
+    end [interface]
+    ]...
+    [
+    interface
+      module <F90 modulename>
+        [<F90 module data type declarations>]
+        [<F90 module routine signatures>]
+      end [module [<F90 modulename>]]
+    end [interface]
+    ]...
+  end [python module [<modulename>]]
+
+Here brackets ``[]`` indicate a optional part, dots ``...`` indicate
+one or more of a previous part. So, ``[]...`` reads zero or more of a
+previous part.
+
+
+Fortran/C routine signatures
+=============================
+
+The signature of a Fortran routine has the following structure::
+
+  [<typespec>] function | subroutine <routine name> \
+                [ ( [<arguments>] ) ] [ result ( <entityname> ) ]
+    [<argument/variable type declarations>]
+    [<argument/variable attribute statements>]
+    [<use statements>]
+    [<common block statements>]
+    [<other statements>]
+  end [ function | subroutine [<routine name>] ]
+
+From a Fortran routine signature F2PY generates a Python/C extension
+function that has the following signature::
+
+  def <routine name>(<required arguments>[,<optional arguments>]):
+       ...
+       return <return variables>
+
+The signature of a Fortran block data has the following structure::
+
+  block data [ <block data name> ]
+    [<variable type declarations>]
+    [<variable attribute statements>]
+    [<use statements>]
+    [<common block statements>]
+    [<include statements>]
+  end [ block data [<block data name>] ]
+
+Type declarations
+-------------------
+
+  The definition of the ``<argument/variable type declaration>`` part
+  is
+
+  ::
+
+    <typespec> [ [<attrspec>] :: ] <entitydecl>
+
+  where
+
+  ::
+
+    <typespec> := byte | character [<charselector>] 
+               | complex [<kindselector>] | real [<kindselector>]
+               | double complex | double precision 
+               | integer [<kindselector>] | logical [<kindselector>]
+
+    <charselector> := * <charlen> 
+                   | ( [len=] <len> [ , [kind=] <kind>] )
+                   | ( kind= <kind> [ , len= <len> ] )
+    <kindselector> := * <intlen> | ( [kind=] <kind> )
+
+    <entitydecl> := <name> [ [ * <charlen> ] [ ( <arrayspec> ) ] 
+                          | [ ( <arrayspec> ) ] * <charlen> ]
+                         | [ / <init_expr> / | = <init_expr> ] \
+                           [ , <entitydecl> ]
+
+  and
+
+  + ``<attrspec>`` is a comma separated list of attributes_;
+
+  + ``<arrayspec>`` is a comma separated list of dimension bounds;
+  
+  + ``<init_expr>`` is a `C expression`__.
+
+  + ``<intlen>`` may be negative integer for ``integer`` type
+    specifications. In such cases ``integer*<negintlen>`` represents
+    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:
+
+  The ``<argument/variable attribute statement>`` is
+  ``<argument/variable type declaration>`` without ``<typespec>``.
+  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 <modulename> [ , <rename_list> | , ONLY : <only_list> ]
+
+  where
+
+  ::
+
+     <rename_list> := <local_name> => <use_name> [ , <rename_list> ]
+
+  Currently F2PY uses ``use`` statement only for linking call-back
+  modules and ``external`` arguments (call-back functions), see 
+  `Call-back arguments`_.
+
+Common block statements:
+
+  The definition of the ``<common block statement>`` part is
+
+  ::
+
+    common / <common name> / <shortentitydecl>
+
+  where
+
+  ::
+
+    <shortentitydecl> := <name> [ ( <arrayspec> ) ] [ , <shortentitydecl> ]
+
+  One ``python module`` block should not contain two or more
+  ``common`` blocks with the same name. Otherwise, the latter ones are
+  ignored. 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>``.
+
+Other statements:
+
+  The ``<other statement>`` part refers to any other Fortran language
+  constructs that are not described above. F2PY ignores most of them
+  except
+
+  + ``call`` statements and function calls of ``external`` arguments
+    (`more details`__?);
+
+__ external_
+
+  + ``include`` statements
+
+      ::
+
+        include '<filename>'
+        include "<filename>"
+
+      If a file ``<filename>`` does not exist, the ``include``
+      statement is ignored. Otherwise, the file ``<filename>`` is
+      included to a signature file.  ``include`` statements can be used
+      in any part of a signature file, also outside the Fortran/C
+      routine signature blocks.
+
+  + ``implicit`` statements
+
+      ::
+
+        implicit none
+	implicit <list of implicit maps>
+
+      where
+
+      ::
+
+        <implicit map> := <typespec> ( <list of letters or range of letters> )
+
+      Implicit rules are used to deterimine 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 real (a-h,o-z,$_), integer (i-m)
+
+  + ``entry`` statements
+
+      ::
+
+        entry <entry name> [([<arguments>])]
+
+      F2PY generates wrappers to 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.
+
+  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 explicitely specify the arguments of the
+      corresponding prototype::
+
+        extern <return type> FUNC_F(<routine name>,<ROUTINE NAME>)(<callprotoargument>);
+ 
+  + ``fortranname [<acctual Fortran/C routine name>]``
+      You can use arbitrary ``<routine name>`` for a given Fortran/C
+      function. Then you have to specify 
+      ``<acctual Fortran/C routine name>`` with this statement.
+
+      If ``fortranname`` statement is used without
+      ``<acctual 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 twise inside ``python
+      module`` block then the second multi-line block is inserted
+      after the definition of external routines.
+
+      When used inside ``<routine singature>``, 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 <multi-line 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.
+
+  __ http://www.python.org/doc/current/ext/ext.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.
+
+  Note that 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.
+
+  If Python ``None`` object is used as an 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.
+
+``dimension(<arrayspec>)``
+  The corresponding variable is considered as an array with given
+  dimensions 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" Numeric 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 Numeric and is
+      effective only if ``intent(c)`` is used. Fortran-contiguousness
+      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
+      Numeric 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 an 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
+      multi-dimensional arrays are C-contiguous.
+
+  + ``hide``
+      The 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::
+
+        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
+      multi-dimensional 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-contiguousness overlap in one-dimensional cases.
+
+      If ``intent(c)`` is used as an statement but without entity
+      declaration list, then F2PY adds ``intent(c)`` attibute to all
+      arguments.
+
+      Also, when wrapping C functions, one must use ``intent(c)``
+      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
+      contiguousness 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
+      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)``.
+
+  The following rules apply:
+
+  + If no ``intent(in | inout | out | hide)`` is 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``.
+
+``check([<C-booleanexpr>])``
+  Perform consistency check of arguments by evaluating
+  ``<C-booleanexpr>``; if ``<C-booleanexpr>`` returns 0, an exception
+  is raised.
+
+  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.
+
+``depend([<names>])``
+  This declares that the corresponding argument depends on the values
+  of variables in the list ``<names>``. 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
+  used then F2PY determines dependence relations automatically. Use
+  ``depend()`` to disable 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
+  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.
+
+.. _external:
+
+``external``
+  The corresponding argument is a function provided by user. The
+  signature of this so-called 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
+
+  ::
+
+    external cb_sub, cb_fun
+    integer n
+    real a(n),r
+    call cb_sub(a,n)
+    r = cb_fun(4)
+
+  the following call-back signatures::
+
+    subroutine cb_sub(a,n)
+        real dimension(n) :: a
+        integer optional,check(len(a)>=n),depend(a) :: n=len(a)
+    end subroutine cb_sub
+    function cb_fun(e_4_e) result (r)
+        integer :: e_4_e
+        real :: r
+    end function cb_fun
+
+  The corresponding user-provided Python function are then::
+
+    def cb_sub(a,[n]):
+        ...
+        return
+    def cb_fun(e_4_e):
+        ...
+        return r
+
+  See also ``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.
+
+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.
+
+F2PY directive has 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:
+
+  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.
+
+C expressions
+--------------
+
+C expressions are used in the following parts of signature files:
+
+* ``<init_expr>`` of variable initialization;
+* ``<C-booleanexpr>`` of the ``check`` attribute;
+* ``<arrayspec> of the ``dimension`` attribute;
+* ``callstatement`` statement, here also a C multi-line block can be used.
+
+A C expression may contain:
+
+* standard C constructs;
+* functions from ``math.h`` and ``Python.h``;
+* variables from the argument list, presumably initialized before
+  according to given dependence relations;
+* the following CPP macros:
+
+  ``rank(<name>)``
+    Returns the rank of an array ``<name>``.
+  ``shape(<name>,<n>)``
+    Returns the ``<n>``-th dimension of an array ``<name>``.
+  ``len(<name>)``
+    Returns the lenght of an array ``<name>``.
+  ``size(<name>)``
+    Returns the size of an array ``<name>``.
+  ``slen(<name>)``
+    Returns the length of a string ``<name>``.
+
+For initializing an array ``<array name>``, F2PY generates a loop over
+all indices and dimensions that executes the following
+pseudo-statement::
+
+  <array name>(_i[0],_i[1],...) = <init_expr>;
+
+where ``_i[<i>]`` refers to the ``<i>``-th index value and that runs
+from ``0`` to ``shape(<array name>,<i>)-1``.
+
+For example, a function ``myrange(n)`` generated from the following
+signature
+
+::
+
+       subroutine myrange(a,n)
+         fortranname        ! myrange is a dummy wrapper
+         integer intent(in) :: n
+         real*8 intent(c,out),dimension(n),depend(n) :: a = _i[0]
+       end subroutine myrange
+
+is equivalent to ``Numeric.arange(n,typecode='d')``.
+
+.. topic:: Warning!
+
+  F2PY may lower cases also in C expressions when scanning Fortran codes
+  (see ``--[no]-lower`` option).
+
+Multi-line blocks
+------------------
+
+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, multi-line blocks can be used in the following constructs:
+
++ as a C expression of the ``callstatement`` statement;
+
++ as a C type specification of the ``callprotoargument`` statement;
+
++ as a C code block of the ``usercode`` statement;
+
++ as a list of C arrays of the ``pymethoddef`` statement;
+
++ as documentation string.
+
+==================================
+Using F2PY bindings in Python
+==================================
+
+All wrappers (to Fortran/C routines or to common blocks or to Fortran
+90 module data) generated by F2PY are exposed to Python as ``fortran``
+type objects.  Routine wrappers are callable ``fortran`` type objects
+while wrappers to Fortran data have attributes referring to data
+objects. 
+
+All ``fortran`` type object 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 an
+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).
+
+.. topic:: Example
+
+  Consider a `Fortran 77 file`__ ``ftype.f``:
+
+  .. include:: ftype.f
+     :literal:
+
+  and build a wrapper using::
+
+    f2py -c ftype.f -m ftype
+
+  __ ftype.f
+
+  In Python:
+
+  .. include:: ftype_session.dat
+     :literal:
+
+
+Scalar arguments
+=================
+
+In general, a scalar argument of a F2PY generated wrapper function can
+be 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.
+
+``intent(inout)`` scalar arguments are assumed to be array objects in
+order to *in situ* changes to be effective. It is recommended to use
+arrays with proper type but also other types work.
+
+.. topic:: Example
+
+  Consider the following `Fortran 77 code`__:
+
+    .. include:: scalar.f
+       :literal:
+
+  and wrap it using ``f2py -c -m scalar scalar.f``.
+
+  __ scalar.f
+
+  In Python:
+
+     .. include:: scalar_session.dat
+        :literal:
+
+
+String arguments
+=================
+
+F2PY generated wrapper functions accept (almost) any Python object as
+a string argument, ``str`` is applied for non-string objects.
+Exceptions are Numeric 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 that
+expected, additional memory is allocated and filled with ``\0``.
+
+Because Python strings are immutable, an ``intent(inout)`` argument
+expects an array version of a string in order to *in situ* changes to
+be effective.
+
+.. topic:: Example
+  
+  Consider the following `Fortran 77 code`__:
+
+  .. include:: string.f
+     :literal:
+
+  and wrap it using ``f2py -c -m mystring string.f``.
+
+  __ string.f
+
+  Python session:
+
+  .. include:: string_session.dat
+     :literal:
+
+
+Array arguments
+================
+
+In general, array arguments of F2PY generated wrapper functions accept
+arbitrary sequences that can be transformed to Numeric 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 Numeric 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.
+
+There are two types of proper-contiguous Numeric arrays:
+
+* Fortran-contiguous arrays when data is stored column-wise,
+  i.e. 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.
+
+For one-dimensional arrays these notions coincide.
+
+For example, an 2x2 array ``A`` is Fortran-contiguous if its elements
+are stored in memory in the following order::
+
+  A[0,0] A[1,0] A[0,1] A[1,1]
+
+and C-contiguous if the order is as follows::
+
+  A[0,0] A[0,1] A[1,0] A[1,1]
+
+To test whether an array is C-contiguous, use ``.iscontiguous()``
+method of Numeric arrays.  To test for Fortran-contiguousness, all
+F2PY generated extension modules provide a function
+``has_column_major_storage(<array>)``. This function is equivalent to
+``Numeric.transpose(<array>).iscontiguous()`` but more efficient.
+
+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 multi-dimensional 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.
+
+To transform input arrays to column major storage order before passing
+them to Fortran routines, use a function
+``as_column_major_storage(<array>)`` that is provided by all F2PY
+generated extension modules.
+
+.. topic:: Example
+
+  Consider `Fortran 77 code`__:
+
+  .. include:: array.f
+     :literal:
+
+  and wrap it using ``f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1``.
+
+  __ array.f
+
+  In Python:
+
+  .. include:: array_session.dat
+     :literal:
+
+Call-back arguments
+====================
+
+F2PY supports calling Python functions from Fortran or C codes.
+
+
+.. topic:: Example
+
+  Consider the following `Fortran 77 code`__
+
+  .. include:: callback.f
+     :literal:
+
+  and wrap it using ``f2py -c -m callback callback.f``.
+
+  __ callback.f
+
+  In Python:
+
+  .. include:: callback_session.dat
+     :literal:
+
+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
+signatures.
+
+.. topic:: Example
+
+  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
+  call-back arguments correctly. First, we create an initial signature
+  file ``callback2.pyf`` using F2PY::
+
+    f2py -m callback2 -h callback2.pyf callback.f
+
+  Then modify it as follows
+
+  .. include:: callback2.pyf
+     :literal:
+
+  Finally, 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.
+
+  __ callback.f
+
+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.
+
+.. topic:: Example
+
+  Consider the following `Fortran 77 subroutine`__ that takes an array
+  and applies a function ``func`` to its elements.
+
+  .. include:: calculate.f
+     :literal:
+
+  __ calculate.f
+
+  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).
+
+  Finally, build an extension module using::
+
+    f2py -c -m foo calculate.f
+
+  In Python:
+
+  .. include:: calculate_session.dat
+     :literal:
+
+The function is included as an argument to the python function call to
+the FORTRAN subroutine eventhough 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 callback function may also be explicitly set in the module.
+Then it is not necessary to pass the function in the argument list to
+the FORTRAN function. This may be desired if the FORTRAN function calling
+the python callback function is itself called by another FORTRAN function.
+
+.. topic:: Example
+
+  Consider the following `Fortran 77 subroutine`__.
+
+  .. include:: extcallback.f
+     :literal:
+
+  __ extcallback.f
+
+  and wrap it using ``f2py -c -m pfromf extcallback.f``.
+
+  In Python:
+
+  .. include:: extcallback_session.dat
+     :literal:
+
+Resolving arguments to call-back functions
+------------------------------------------
+
+F2PY generated interface is 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.
+
+If a F2PY generated wrapper function expects the following call-back
+argument::
+
+  def fun(a_1,...,a_n):
+     ...
+     return x_1,...,x_k
+
+but the following Python function
+
+::
+
+  def gun(b_1,...,b_m):
+     ...
+     return y_1,...,y_l
+
+is provided by an 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``:
+
+* If ``p==0`` then ``gun(a_1,...,a_q)`` is called, here
+  ``q=min(m,n)``.
+* If ``n+p<=m`` then ``gun(a_1,...,a_n,e_1,...,e_p)`` is called.
+* If ``p<=m<n+p`` then ``gun(a_1,...,a_q,e_1,...,e_p)`` is called, here
+  ``q=m-p``.
+* If ``p>m`` then ``gun(e_1,...,e_m)`` is called.
+* 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 ``k<l``, then ``y_{k+1},...,y_l`` are ignored.
+* If ``k>l``, then only ``x_1,...,x_l`` are set.
+
+
+
+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
+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 Numeric array
+objects (multi-dimensional arrays are Fortran-contiguous) that
+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.
+
+.. topic:: Example
+
+  Consider the following `Fortran 77 code`__
+
+  .. include:: common.f
+     :literal:
+
+  and wrap it using ``f2py -c -m common common.f``.
+
+  __ common.f
+
+  In Python:
+
+  .. include:: common_session.dat
+     :literal:
+
+Fortran 90 module data
+=======================
+
+The F2PY interface to Fortran 90 module data is similar to Fortran 77
+common blocks.
+
+.. topic:: Example
+
+  Consider the following `Fortran 90 code`__
+
+  .. include:: moddata.f90
+     :literal:
+
+  and wrap it using ``f2py -c -m moddata moddata.f90``.
+
+  __ moddata.f90
+
+  In Python:
+
+  .. include:: moddata_session.dat
+     :literal:
+
+Allocatable arrays
+-------------------
+
+F2PY has basic support for Fortran 90 module allocatable arrays.
+
+.. topic:: Example
+
+  Consider the following `Fortran 90 code`__
+
+  .. include:: allocarr.f90
+     :literal:
+
+  and wrap it using ``f2py -c -m allocarr allocarr.f90``.
+
+  __ allocarr.f90
+
+  In Python:
+
+  .. include:: allocarr_session.dat
+     :literal:
+
+
+===========
+Using F2PY
+===========
+
+F2PY can be used either as a command line tool ``f2py`` or as a Python
+module ``f2py2e``.
+
+Command ``f2py``
+=================
+
+When used as a command line tool, ``f2py`` has three major modes,
+distinguished by the usage of ``-c`` and ``-h`` switches:
+
+1. To scan Fortran sources and generate a signature file, use
+
+  ::
+
+    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).
+
+  If ``<filename.pyf>`` is specified as ``stdout`` then signatures
+  are send to standard output instead of a file.
+
+  Among other options (see below), the following options can be used
+  in this mode:
+
+  ``--overwrite-signature``
+    Overwrite existing signature file.
+
+2. To construct an extension module, use
+
+  ::
+
+    f2py <options> <fortran files>          \
+      [[ only: <fortran functions>  : ]     \
+       [ skip: <fortran functions>  : ]]... \
+      [<fortran files> ...]
+
+  The constructed extension module is saved as
+  ``<modulename>module.c`` to the current directory.
+
+  Here ``<fortran files>`` may also contain signature files.
+  Among other options (see below), the following options can be used
+  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.
+
+  ``-include'<includefile>'``
+    Add a CPP ``#include`` statement to the extension module source.
+    ``<includefile>`` should be given in one of the following forms::
+
+      "filename.ext"
+      <filename.ext>
+    
+    The include statement is inserted just before the wrapper
+    functions. This feature enables using arbitrary C functions
+    (defined in ``<includefile>``) in F2PY generated wrappers.
+
+    This option is deprecated. Use ``usercode`` statement to specify
+    C codelets directly in signature filess
+
+
+  ``--[no-]wrap-functions``
+
+    Create Fortran subroutine wrappers to Fortran functions.
+    ``--wrap-functions`` is default because it ensures maximum
+    portability and compiler independence.
+
+  ``--include-paths <path1>:<path2>:..``
+    Search include files from given directories.
+
+  ``--help-link [<list of resources names>]`` 
+    List system resources found by ``scipy_distutils/system_info.py``.
+    For example, try ``f2py --help-link lapack_opt``.
+
+3. To build an extension module, use
+
+  ::
+
+    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
+  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
+  directory.
+
+  If ``<fortran files>`` does not contain a signature file, then an
+  extension module is constructed by scanning all Fortran source codes
+  for routine signatures.
+
+  Among other options (see below) and options described in previous
+  mode, the following options can be used in this mode:
+
+  ``--help-fcompiler``
+    List available Fortran compilers.
+  ``--help-compiler`` [depreciated]
+    List available Fortran compilers.
+  ``--fcompiler=<Vendor>``
+    Specify Fortran compiler type by vendor.
+  ``--f77exec=<path>``
+    Specify the path to F77 compiler 
+  ``--fcompiler-exec=<path>`` [depreciated]
+    Specify the path to F77 compiler 
+  ``--f90exec=<path>``
+    Specify the path to F90 compiler
+  ``--f90compiler-exec=<path>`` [depreciated]
+    Specify the path to F90 compiler
+
+  ``--f77flags=<string>``
+    Specify F77 compiler flags
+  ``--f90flags=<string>``
+    Specify F90 compiler flags
+  ``--opt=<string>``
+    Specify optimization flags
+  ``--arch=<string>``
+    Specify architecture specific optimization flags
+  ``--noopt``
+    Compile without optimization
+  ``--noarch``
+    Compile without arch-dependent optimization
+  ``--debug``
+    Compile with debugging information
+
+  ``-l<libname>``
+    Use the library ``<libname>`` when linking.
+  ``-D<macro>[=<defn=1>]``
+    Define macro ``<macro>`` as ``<defn>``.
+  ``-U<macro>``
+    Define macro ``<macro>``
+  ``-I<dir>``
+    Append directory ``<dir>`` to the list of directories searched for
+    include files.
+  ``-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
+    ``scipy_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.
+
+  When building an extension module, a combination of the following
+  macros may be required for non-gcc Fortran compilers::
+
+    -DPREPEND_FORTRAN
+    -DNO_APPEND_FORTRAN
+    -DUPPERCASE_FORTRAN
+
+  To test the performance of F2PY generated interfaces, use
+  ``-DF2PY_REPORT_ATEXIT``. Then a report of various timings is
+  printed out at the exit of Python. This feature may not work on
+  all platforms, currently only Linux platform is supported.
+
+  To see whether F2PY generated interface performs copies of array
+  arguments, use ``-DF2PY_REPORT_ON_ARRAY_COPY=<int>``. When the size
+  of an array argument is larger than ``<int>``, a message about
+  the coping is sent to ``stderr``.
+
+Other options:
+
+``-m <modulename>``
+  Name of an extension module. Default is ``untitled``. 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``
+  without the ``-h`` switch.
+``--build-dir <dirname>``
+  All F2PY generated files are created in ``<dirname>``.  Default is
+  ``tempfile.mktemp()``.
+``--quiet``
+  Run quietly.
+``--verbose``
+  Run with extra verbosity.
+``-v``
+  Print f2py version ID and exit.
+
+Execute ``f2py`` without any options to get an up-to-date list of
+available options.
+
+Python module ``f2py2e``
+=========================
+
+.. topic:: Warning
+
+  The current Python interface to ``f2py2e`` module is not mature and
+  may change in future depending on users needs.
+
+The following functions are provided by the ``f2py2e`` module:
+
+``run_main(<list>)``
+  Equivalent to running::
+
+    f2py <args>
+
+  where ``<args>=string.join(<list>,' ')``, but in Python.  Unless
+  ``-h`` is used, this function returns a dictionary containing
+  information on generated modules and their dependencies on source
+  files.  For example, the command ``f2py -m scalar scalar.f`` can be
+  executed from Python as follows
+
+  .. include:: run_main_session.dat
+     :literal:
+
+  You cannot build extension modules with this function, that is,
+  using ``-c`` is not allowed. Use ``compile`` command instead, see
+  below.
+
+``compile(source, modulename='untitled', extra_args='', verbose=1, source_fn=None)``
+
+  Build extension module from Fortran 77 source string ``source``. 
+  Return 0 if successful.
+  Note that this function actually calls ``f2py -c ..`` from shell to
+  ensure safety of the current Python process.
+  For example,
+
+  .. include:: compile_session.dat
+    :literal:
+
+==========================
+Using ``scipy_distutils``
+==========================
+
+``scipy_distutils`` is part of the SciPy_ project and aims to extend
+standard Python ``distutils`` 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`__:
+
+  .. include:: setup_example.py
+    :literal:
+
+  Running
+
+  ::
+
+    python setup_example.py build
+
+  will build two extension modules ``scalar`` and ``fib2`` to the
+  build directory.
+
+  __ setup_example.py
+
+``scipy_distutils`` extends ``distutils`` with the following features:
+
+* ``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
+  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.
+
+  Additional options to F2PY process can be given using ``Extension``
+  class argument ``f2py_options``.
+
+``scipy_distutils`` 0.2.2 and up
+================================
+
+* 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
+
+  as well as ``build_ext`` and  ``build_clib`` commands are enhanced 
+  to support Fortran sources.
+
+  Run
+
+  ::
+
+    python <setup.py file> config_fc build_src build_ext --help
+
+  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``
+  command option ``--fcompiler=<Vendor>``. Here ``<Vendor>`` can be one of the
+  following names::
+ 
+    absoft sun mips intel intelv intele intelev nag compaq compaqv gnu vast pg hpux
+
+  See ``scipy_distutils/fcompiler.py`` for up-to-date list of
+  supported compilers or run
+
+  ::
+
+     f2py -c --help-fcompiler
+
+``scipy_distutils`` pre 0.2.2
+=============================
+
+* The following new ``distutils`` commands are defined:
+
+  ``build_flib``
+    to build f77/f90 libraries used by Python extensions;
+  ``run_f2py``
+    to construct Fortran wrapper extension modules.
+
+  Run
+
+  ::
+
+    python <setup.py file> build_flib run_f2py --help
+
+  to see available options for these commands.
+
+* When building Python packages containing Fortran sources, then one
+  can choose different Fortran compilers either by using ``build_flib``
+  command option ``--fcompiler=<Vendor>`` or by defining environment
+  variable ``FC_VENDOR=<Vendor>``. Here ``<Vendor>`` can be one of the
+  following names::
+ 
+    Absoft Sun SGI Intel Itanium NAG Compaq Digital Gnu VAST PG
+
+  See ``scipy_distutils/command/build_flib.py`` for up-to-date list of
+  supported compilers.
+
+======================
+ Extended F2PY usages
+======================
+
+Adding self-written functions to F2PY generated modules
+=======================================================
+
+Self-written 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
+   :literal:
+
+wraps the C library function ``system()``::
+
+  f2py -c spam.pyf
+
+In Python:
+
+.. include:: spam_session.dat
+   :literal:  
+
+Modifying the dictionary of a F2PY generated module
+===================================================
+
+The following example illustrates how to add an user-defined
+variables to a F2PY generated extension module. Given the following
+signature file
+
+.. include:: var.pyf
+  :literal:
+
+compile it as ``f2py -c var.pyf``.
+
+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
+additional details).
+
+In Python:
+
+.. include:: var_session.dat
+  :literal:
+
+.. References
+   ==========
+.. _F2PY: http://cens.ioc.ee/projects/f2py2e/
+.. _Python: http://www.python.org/
+.. _NumPy: http://www.numpy.org/
+.. _SciPy: http://www.scipy.org/
diff --git a/numpy/f2py/docs/usersguide/moddata.f90 b/numpy/f2py/docs/usersguide/moddata.f90
new file mode 100644
index 000000000..0e98f0467
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/moddata.f90
@@ -0,0 +1,18 @@
+module mod
+  integer i
+  integer :: x(4)
+  real, dimension(2,3) :: a
+  real, allocatable, dimension(:,:) :: b 
+contains
+  subroutine foo
+    integer k
+    print*, "i=",i
+    print*, "x=[",x,"]"
+    print*, "a=["
+    print*, "[",a(1,1),",",a(1,2),",",a(1,3),"]"
+    print*, "[",a(2,1),",",a(2,2),",",a(2,3),"]"
+    print*, "]"
+    print*, "Setting a(1,2)=a(1,2)+3"
+    a(1,2) = a(1,2)+3
+  end subroutine foo
+end module mod
diff --git a/numpy/f2py/docs/usersguide/moddata_session.dat b/numpy/f2py/docs/usersguide/moddata_session.dat
new file mode 100644
index 000000000..1ec212f8b
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/moddata_session.dat
@@ -0,0 +1,23 @@
+>>> import moddata
+>>> print moddata.mod.__doc__
+i - 'i'-scalar
+x - 'i'-array(4)
+a - 'f'-array(2,3)
+foo - Function signature:
+  foo()
+
+
+>>> moddata.mod.i = 5  
+>>> moddata.mod.x[:2] = [1,2]
+>>> moddata.mod.a = [[1,2,3],[4,5,6]]
+>>> moddata.mod.foo()                
+ i=           5
+ x=[           1           2           0           0 ]
+ a=[
+ [   1.000000     ,   2.000000     ,   3.000000     ]
+ [   4.000000     ,   5.000000     ,   6.000000     ]
+ ]
+ Setting a(1,2)=a(1,2)+3
+>>> moddata.mod.a               # a is Fortran-contiguous
+array([[ 1.,  5.,  3.],
+       [ 4.,  5.,  6.]],'f')
diff --git a/numpy/f2py/docs/usersguide/run_main_session.dat b/numpy/f2py/docs/usersguide/run_main_session.dat
new file mode 100644
index 000000000..29ecc3dfe
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/run_main_session.dat
@@ -0,0 +1,14 @@
+>>> import f2py2e
+>>> r=f2py2e.run_main(['-m','scalar','docs/usersguide/scalar.f'])
+Reading fortran codes...
+        Reading file 'docs/usersguide/scalar.f'
+Post-processing...
+        Block: scalar
+                        Block: FOO
+Building modules...
+        Building module "scalar"...
+        Wrote C/API module "scalar" to file "./scalarmodule.c"
+>>> print r
+{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py2e/src/fortranobject.h'],
+	 'csrc': ['./scalarmodule.c', 
+                  '/home/users/pearu/src_cvs/f2py2e/src/fortranobject.c']}}
diff --git a/numpy/f2py/docs/usersguide/scalar.f b/numpy/f2py/docs/usersguide/scalar.f
new file mode 100644
index 000000000..c22f639ed
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/scalar.f
@@ -0,0 +1,12 @@
+C FILE: SCALAR.F
+      SUBROUTINE FOO(A,B)
+      REAL*8 A, B
+Cf2py intent(in) a
+Cf2py intent(inout) b
+      PRINT*, "    A=",A," B=",B
+      PRINT*, "INCREMENT A AND B"
+      A = A + 1D0
+      B = B + 1D0
+      PRINT*, "NEW A=",A," B=",B
+      END
+C END OF FILE SCALAR.F
diff --git a/numpy/f2py/docs/usersguide/scalar_session.dat b/numpy/f2py/docs/usersguide/scalar_session.dat
new file mode 100644
index 000000000..4fe8c03b1
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/scalar_session.dat
@@ -0,0 +1,21 @@
+>>> import scalar
+>>> print scalar.foo.__doc__
+foo - Function signature:
+  foo(a,b)
+Required arguments:
+  a : input float
+  b : in/output rank-0 array(float,'d')
+ 
+>>> scalar.foo(2,3)   
+     A=  2. B=  3.
+ INCREMENT A AND B
+ NEW A=  3. B=  4.
+>>> import Numeric
+>>> a=Numeric.array(2)   # these are integer rank-0 arrays
+>>> b=Numeric.array(3)
+>>> scalar.foo(a,b)
+     A=  2. B=  3.
+ INCREMENT A AND B
+ NEW A=  3. B=  4.
+>>> print a,b            # note that only b is changed in situ
+2 4
\ No newline at end of file
diff --git a/numpy/f2py/docs/usersguide/setup_example.py b/numpy/f2py/docs/usersguide/setup_example.py
new file mode 100644
index 000000000..a7d27403a
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/setup_example.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+# File: setup_example.py
+
+from scipy_distutils.core import Extension
+
+ext1 = Extension(name = 'scalar',
+                 sources = ['scalar.f'])
+ext2 = Extension(name = 'fib2',
+                 sources = ['fib2.pyf','fib1.f'])
+
+if __name__ == "__main__":
+    from scipy_distutils.core import setup
+    setup(name = 'f2py_example',
+          description       = "F2PY Users Guide examples",
+          author            = "Pearu Peterson",
+          author_email      = "pearu@cens.ioc.ee",
+          ext_modules = [ext1,ext2]
+          )
+# End of setup_example.py
diff --git a/numpy/f2py/docs/usersguide/spam.pyf b/numpy/f2py/docs/usersguide/spam.pyf
new file mode 100644
index 000000000..21ea18b77
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/spam.pyf
@@ -0,0 +1,19 @@
+!    -*- f90 -*-
+python module spam
+    usercode '''
+  static char doc_spam_system[] = "Execute a shell command.";
+  static PyObject *spam_system(PyObject *self, PyObject *args)
+  {
+    char *command;
+    int sts;
+
+    if (!PyArg_ParseTuple(args, "s", &command))
+        return NULL;
+    sts = system(command);
+    return Py_BuildValue("i", sts);
+  }
+    '''
+    pymethoddef '''
+    {"system",  spam_system, METH_VARARGS, doc_spam_system},
+    '''
+end python module spam
diff --git a/numpy/f2py/docs/usersguide/spam_session.dat b/numpy/f2py/docs/usersguide/spam_session.dat
new file mode 100644
index 000000000..7f99d13f9
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/spam_session.dat
@@ -0,0 +1,5 @@
+>>> import spam
+>>> status = spam.system('whoami')
+pearu
+>> status = spam.system('blah')
+sh: line 1: blah: command not found
\ No newline at end of file
diff --git a/numpy/f2py/docs/usersguide/string.f b/numpy/f2py/docs/usersguide/string.f
new file mode 100644
index 000000000..9246f02e7
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/string.f
@@ -0,0 +1,21 @@
+C FILE: STRING.F
+      SUBROUTINE FOO(A,B,C,D)
+      CHARACTER*5 A, B
+      CHARACTER*(*) C,D
+Cf2py intent(in) a,c
+Cf2py intent(inout) b,d
+      PRINT*, "A=",A
+      PRINT*, "B=",B
+      PRINT*, "C=",C
+      PRINT*, "D=",D
+      PRINT*, "CHANGE A,B,C,D"
+      A(1:1) = 'A'
+      B(1:1) = 'B'
+      C(1:1) = 'C'
+      D(1:1) = 'D'
+      PRINT*, "A=",A
+      PRINT*, "B=",B
+      PRINT*, "C=",C
+      PRINT*, "D=",D
+      END
+C END OF FILE STRING.F
diff --git a/numpy/f2py/docs/usersguide/string_session.dat b/numpy/f2py/docs/usersguide/string_session.dat
new file mode 100644
index 000000000..64ebcb3f4
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/string_session.dat
@@ -0,0 +1,27 @@
+>>> import mystring
+>>> print mystring.foo.__doc__
+foo - Function signature:
+  foo(a,b,c,d)
+Required arguments:
+  a : input string(len=5)
+  b : in/output rank-0 array(string(len=5),'c')
+  c : input string(len=-1)
+  d : in/output rank-0 array(string(len=-1),'c')
+
+>>> import Numeric
+>>> a=Numeric.array('123')
+>>> b=Numeric.array('123')
+>>> c=Numeric.array('123')
+>>> d=Numeric.array('123')
+>>> mystring.foo(a,b,c,d)
+ A=123
+ B=123
+ C=123
+ D=123
+ CHANGE A,B,C,D
+ A=A23
+ B=B23
+ C=C23
+ D=D23
+>>> a.tostring(),b.tostring(),c.tostring(),d.tostring()
+('123', 'B23', '123', 'D23')
\ No newline at end of file
diff --git a/numpy/f2py/docs/usersguide/var.pyf b/numpy/f2py/docs/usersguide/var.pyf
new file mode 100644
index 000000000..8275ff3af
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/var.pyf
@@ -0,0 +1,11 @@
+!    -*- f90 -*-
+python module var
+  usercode '''
+    int BAR = 5;
+  '''
+  interface
+    usercode '''
+      PyDict_SetItemString(d,"BAR",PyInt_FromLong(BAR));
+    '''
+  end interface
+end python module
diff --git a/numpy/f2py/docs/usersguide/var_session.dat b/numpy/f2py/docs/usersguide/var_session.dat
new file mode 100644
index 000000000..fb0f798bf
--- /dev/null
+++ b/numpy/f2py/docs/usersguide/var_session.dat
@@ -0,0 +1,3 @@
+>>> import var
+>>> var.BAR
+5
\ No newline at end of file