diff --git a/INSTALL.txt b/INSTALL.txt
new file mode 100644
index 0000000000000000000000000000000000000000..5ec05d92fa399bf3b5480c45be8f86e37cd39730
--- /dev/null
+++ b/INSTALL.txt
@@ -0,0 +1,265 @@
+=============================
+Building and installing kwant
+=============================
+
+Prerequisites
+=============
+
+Building kwant requires
+
+ - `Python <http://python.org>`_ 2.6 or newer;
+
+ - `SciPy <http://scipy.org>`_ 0.7.2 or newer;
+
+ - `LAPACK <http://netlib.org/lapack/>`_ and `BLAS <http://netlib.org/blas/>`_;
+
+ - tinyarray, a NumPy-like Python package optimized for very small arrays;
+
+ - An environment which allows to compile Python extensions written in C and
+ C++.
+
+The following software is highly recommended though not strictly required:
+
+ - `matplotlib <http://matplotlib.sourceforge.net/>`_, for kwant's plotting
+ module and the tutorial;
+
+ - `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_, a sparse linear algebra library
+ that will in many cases speed up kwant several times and reduce the memory
+ footprint.
+
+Suggested:
+
+ - The `nose <http://nose.readthedocs.org/>`_ testing framework is required to
+ run the extensive tests included with kwant.
+
+Generic instructions
+====================
+
+kwant can be built and installed following the `usual Python conventions
+<http://docs.python.org/install/index.html>`_ by running the following commands
+in the root directory of the kwant distribution. ::
+
+ python setup.py build
+ python setup.py install
+
+Depending on your system, you might have to run the second command with
+administrator privileges (e.g. prefixing it with ``sudo``).
+
+To check successful installation try executing some scripts in the ``tutorial``
+subdirectory, e.g.::
+
+ cd tutorial
+ python 1-quantum_wire_revisited.py
+
+If "nose" is installed, you can also run the tests ::
+
+ python -c 'import kwant; kwant.test()'
+
+from some directory *other* than the kwant distribution's root directory.
+
+
+System-specific instructions
+============================
+
+Unix-like systems (Linux)
+-------------------------
+
+1. Install the required software. On Debian/Ubuntu-like systems this can be
+ done by running ::
+
+ sudo apt-get install python-dev scipy-dev g++ libmumps-scotch-dev python-matplotlib python-nose
+
+2. Unpack tinyarray, enter its directory, build and install. ::
+
+ python setup.py build
+ sudo python setup.py install
+
+3. Inside the kwant source distribution's root directory run ::
+
+ python setup.py build
+ sudo python setup.py install
+
+By default the package will be installed under ``/usr/local``. You can
+change this using the ``--prefix`` option, e.g.::
+
+ sudo python setup.py install --prefix=/opt
+
+If you would like to install kwant into your home directory only you can use ::
+
+ python setup.py install --home=~
+
+This does not require root privileges. If you install kwant in this way
+be sure to tell python where to find it. This can be done by setting the
+``PYTHONPATH`` environment variable::
+
+ export PYTHONPATH=$HOME/lib/python
+
+You can make this setting permanent by adding this line to the file
+``.bashrc`` (or equivalent) in your home directory.
+
+
+Mac OS X
+--------
+
+(Please help to improve these instructions.)
+
+These are instructions for installing kwant on Mac computers using the software
+MacPorts. MacPorts allows to download and install a large number of
+open-source software packages. There exist also other ways to install the
+required libraries.
+
+Following these instructions will install kwant without `MUMPS
+<http://graal.ens-lyon.fr/MUMPS/>`_. With MUMPS kwant will run several times
+faster and will use less memory.
+
+These instructions were verified in November 2011 under Mac OS X 10.6.8.
+
+1. Install a fresh version of Xcode (Apple's development environment).
+
+2. Install `MacPorts <http://www.macports.org/>`_. After installation, you
+ probably want to update its data base with ::
+
+ sudo port selfupdate
+
+3. OPTIONAL: Install a more recent gcc compiler::
+
+ sudo port install mp-gcc44
+
+ (``port search gcc`` will give you the available versions) and set it as
+ your default ::
+
+ sudo port select --set gcc mp-gcc44
+
+ (``port select gcc`` will give you the possible choices)
+
+4. Install the required packages::
+
+ sudo port install python27
+ sudo port install py27-scipy
+ sudo port install py27-matplotlib
+
+5. You might need to modify the matplotlib configuration file::
+
+ > python
+ >>> import matplotlib
+ >>> matplotlib.matplotlib_fname()
+ '/Users/username/.matplotlib/matplotlibrc'
+
+ Edit the corresponding ``matplotlibrc`` configuration file, look for the
+ line starting with backend and modify it to::
+
+ backend : MacOSX
+
+6. Set python 2.7 as your default. ::
+
+ sudo port select --set python python27
+
+7. Unpack tinyarray, enter its directory, build and install. ::
+
+ python setup.py build
+ sudo python setup.py install
+
+8. Go to the kwant directory, build and install. ::
+
+ python setup.py build
+ sudo python setup.py install
+
+
+Microsoft Windows
+-----------------
+
+It should be possible to run kwant under Microsoft Windows but so far no one
+has tried hard enough. We will happily include Windows-specific installation
+instructions in this document once someone contributes them.
+
+A good starting point should be the `free edition of the Enthought Python
+Distribution <http://www.enthought.com/products/epd_free.php>`_.
+
+
+Build configuration
+===================
+
+The setup script of kwant has to know how to link against LAPACK & BLAS, and,
+optionally, MUMPS. Be default it will assume that LAPACK and BLAS can be found
+under their usual names. MUMPS will be not linked against by default, except
+on Debian-based systems when the package ``libmumps-scotch-dev`` is installed.
+
+All these settings can be configured by creating/editing the file
+``build.conf`` in the root directory of the kwant distribution. This
+configuration file consists of sections, one for each dependency, led by a
+[dependency-name] header and followed by name = value entries. Possible names
+are keyword arguments for ``distutils.core.Extension`` (For a complete list,
+see the third table from top of `this document
+<http://docs.python.org/distutils/apiref.html>`_). The corresponding values
+are whitespace-separated lists of strings.
+
+The two currently possible sections are [lapack] and [mumps]. The former
+configures the linking against LAPACK _AND_ BLAS, the latter against MUMPS
+(without LAPACK and BLAS).
+
+Example ``build.conf`` for linking kwant against a self-compiled MUMPS, `SCOTCH
+<http://www.labri.fr/perso/pelegrin/scotch/>`_ and `METIS
+<http://glaros.dtc.umn.edu/gkhome/metis/metis/overview>`_::
+
+ [mumps]
+ libraries = zmumps mumps_common pord metis esmumps scotch scotcherr mpiseq gfortran
+
+Example ``build.conf`` for linking kwant with Intel MKL.::
+
+ [lapack]
+ libraries = mkl_intel_lp64 mkl_sequential mkl_core mkl_def
+ library_dirs = /opt/intel/mkl/lib/intel64
+ extra_link_args = -Wl,-rpath=/opt/intel/mkl/lib/intel64
+
+
+Building the documentation
+==========================
+
+To build the documentation, kwant has to be installed as described above.
+Additionally, the `sphinx documentation generator <http://sphinx.pocoo.org/>`_
+is required.
+
+HTML documentation can be built by entering the ``doc`` subdirectory of the
+kwant package and executing ``make html``. PDF documentation is generated by
+executing ``make latex`` followed by a ``make all-pdf`` in ``doc/build/latex``.
+
+Because of some quirks of how sphinx works, it might be necessary to execute
+``make clean`` between building HTML and PDF documentation. If this is not
+done, sphinx might mistakenly use PNG files for PDF output.
+
+
+Hacking
+=======
+
+To work on kwant itself it is useful to build it in-place. This can be done
+with the following command ::
+
+ python setup.py build_ext -i
+
+The ``kwant`` subdirectory of the source distribution will be thus turned into
+a proper python package which can be imported. To be able to import kwant from
+within python, one can either work in the root directory of the distribution
+(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
+somewhere in the Python search path to the the package subdirectory.
+
+Some conventions to keep in mind:
+
+* Write tests for all the important functionality you add. Be sure not to
+ break existing tests.
+
+* Please keep the code consistent by adhering to the prevailing naming and
+ formatting conventions. We generally follow the `"Style Guide for Python
+ Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
+ `NumPy's "Docstring Standard"
+ <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
+ `Python's "Docstring Conventions"
+ <http://www.python.org/dev/peps/pep-0257/>`_.
+
+Several modules are written in `Cython <http://cython.org/>`_ (.pyx file name
+extension). You will need Cython 0.17.1 if you want to modify them.
+
+kwant includes extensive unit tests which are supposed to cover all of its
+functionality. We use the `nose <http://nose.readthedocs.org/>`_ testing
+framework. To run the tests, execute the command ``nosetests`` from the root
+directory of the package after it has been built in place. You can also
+``import kwant`` inside Python and run ``kwant.test()``.
diff --git a/LICENSE.txt b/LICENSE.txt
new file mode 100644
index 0000000000000000000000000000000000000000..7ca50d880e51c4b4d16d60ef0fbfe7783ebcb340
--- /dev/null
+++ b/LICENSE.txt
@@ -0,0 +1,7 @@
+License
+=======
+
+This software (kwant) is NOT TO BE DISTRIBUTED, neither in part nor as a whole.
+
+The only exception to this is the ``doc/sphinxext`` subdirectory, which is free
+software. (See the file ``LICENSE.txt`` in that subdirectory.)
diff --git a/README.txt b/README.txt
index 939cb1468717701946059ae373811915f3a83f83..fa69879b16fabe6ed812e7e15199a50b4f0d90e1 100644
--- a/README.txt
+++ b/README.txt
@@ -1,123 +1,10 @@
-=============================================================
-kwant, a package for numerical quantum transport calculations
-=============================================================
-
-Licence
-=======
-
-This software is NOT TO BE DISTRIBUTED, neither in part nor as a whole.
-
-The only exception to this is the ``doc/sphinxext`` subdirectory, which is free
-software. (See the file ``LICENSE.txt`` in that subdirectory.)
-
-
-Installation from source
-========================
-
-The prerequisites are
-
- - More or less current versions of `Python <http://python.org>`_ and `SciPy
- <http://scipy.org>`_. Python 2.6 and scipy 0.7.2 should be enough.
-
- - An environment which allows to compile Python extensions written in C and
- C++. This includes a C/C++ compiler and Python C headers. The latter might
- be provided in a separate package like ``python-dev``.
-
- - Some incarnation of `LAPACK <http://www.netlib.org/lapack/>`_.
-
-Recommended:
-
- - `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_ will in many cases speed up kwant
- several times and reduce the memory footprint.
-
- - `pycairo <http://cairographics.org/pycairo/>`_
-
- - `matplotlib <http://matplotlib.sourceforge.net/>`_
-
-kwant can be built and installed using distutils, following standard Python
-conventions. To build and install, run the following commands in the root
-directory of the package. ::
-
- python setup.py build
- python setup.py install
-
-The second command has to be run as root (e.g. prefixing it with ``sudo``). By
-default the package will be installed under ``/usr/local``. You can change
-this using the ``--prefix`` option, e.g.::
-
- python setup.py install --prefix=/opt
-
-If you would like to install kwant into your home directory only you can use ::
-
- python setup.py install --home=~
-
-This does not require superuser priviledges. If you install kwant in this way
-be sure to tell python where to find it. This can be done by setting the
-``PYTHONPATH`` environment variable::
-
- export PYTHONPATH=$HOME/lib/python
-
-You can make this setting permanent by adding this line to the file
-``.bashrc`` in your home directory.
-
-To check successful installation try executing some scripts in the ``examples``
-subdirectory.
-
-
-Documentation
-=============
-
-To build the documentation, kwant has to be installed as described in the
-previous section. The `sphinx documentation generator
-<http://sphinx.pocoo.org/>`_ is required.
-
-HTML documentation can be built by entering the ``doc`` subdirectory of the
-kwant package and executing ``make html``. PDF documentation is generated by
-executing ``make latex`` followed by a ``make all-pdf`` in ``doc/build/latex``.
-
-Because of some quirks of how sphinx works, it might be necessary to execute
-``make clean`` between building HTML and PDF documentation. If this is not
-done, sphinx might mistakenly use PNG files for PDF output.
-
-Please consult the documentation for further information on how to use kwant.
-
-
-Hacking
-=======
-
-To work on kwant itself it is useful to build it in-place. This can be done
-with the following command ::
-
- python setup.py build_ext -i
-
-The ``kwant`` subdirectory of the source distribution will be thus turned into
-a proper python package which can be imported. To be able to import kwant from
-within python, one can either work in the root directory of the distribution
-(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
-somewhere in the Python search path to the the package subdirectory.
-
-Some conventions to keep in mind:
-
-* Write tests for all the important functionality you add. Be sure not to
- break existing tests.
-
-* Please keep the code consistent by adhering to the prevailing naming and
- formatting conventions. We generally follow the `"Style Guide for Python
- Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
- `NumPy's "Docstring Standard"
- <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
- `Python's "Docstring Conventions"
- <http://www.python.org/dev/peps/pep-0257/>`_.
-
-Several modules are written in `Cython <http://cython.org/>`_ (.pyx file name
-extension). You will need Cython 0.17.1 if you want to modify them.
-
-
-Tests
-=====
-
-kwant includes extensive unit tests which are supposed to cover all of its
-functionality. We use the `nose
-<http://somethingaboutorange.com/mrl/projects/nose/>`_ testing framework. To
-run the tests, execute the command ``nosetests`` from the root directory of the
-package after it has been built in place.
+kwant is a Python package for numerical quantum transport calculations. It
+aims to be an user-friendly, powerful and efficient toolbox for the simulation
+of physical systems governed by tight-binding Hamiltonians. It is currently
+suitable for calculations of Landauer transport (conductance, noise),
+dispersion relations, modes, wavefunctions, various Green functions, local
+density of states.
+
+See the file INSTALL.txt for installation instructions and LICENSE.txt for
+legal information. Complete reference documentation and a tutorial are also
+available.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 411aff34b1efce246fff38a7be91291e6dbe31e1..bda40fa1b22f128172b3db716e9ba24609f6bf8f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -2,10 +2,18 @@
kwant documentation
===================
+.. include:: ../../README.txt
+ :end-before: See the file INSTALL.txt
+
+.. toctree::
+ :maxdepth: 1
+
+ Installation instructions <install>
+
.. toctree::
:maxdepth: 1
- README file (includes installation instructions) <readme>
+ license
.. toctree::
:maxdepth: 1
diff --git a/doc/source/install.rst b/doc/source/install.rst
new file mode 100644
index 0000000000000000000000000000000000000000..442a6adf3e094c49bc6bc537fa9ea4196a057379
--- /dev/null
+++ b/doc/source/install.rst
@@ -0,0 +1 @@
+.. include:: ../../INSTALL.txt
diff --git a/doc/source/license.rst b/doc/source/license.rst
new file mode 100644
index 0000000000000000000000000000000000000000..96399e5b74f55536c8e6677ef818de48cd4121f6
--- /dev/null
+++ b/doc/source/license.rst
@@ -0,0 +1 @@
+.. include:: ../../LICENSE.txt
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index 8ecf341e8f24ee0691316b27e0f658f6e5c654db..0000000000000000000000000000000000000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.txt
diff --git a/doc/source/tutorial/introduction.rst b/doc/source/tutorial/introduction.rst
index 77035e0f65887ec63ac684d2cd8e67e1232223a3..c4337dc1df97e6c401c59c1c2e71cc4161ebaf4c 100644
--- a/doc/source/tutorial/introduction.rst
+++ b/doc/source/tutorial/introduction.rst
@@ -1,12 +1,6 @@
Introduction
============
-kwant is currently suitable for calculating Landauer transport and
-calculating dispersions of various tight binding systems. Possible future
-extensions are calculations of local density of states, supercurrent, of
-various transport properties like Wigner-Smith delay time or Goos-Hänchen
-shift, Boltzmann transport, etc.
-
There are two steps in obtaining a numerical solution to a problem: The first
is defining the problem in a computer-accessible way, the second solving it.
The aim of a software package like kwant is to make both steps easier.