reorganize docs (mostly for the latex version)

ACKNOWLEDGEMENTS

@@ -2,4 +2,10 @@
 Suggested acknowledgements
 ==========================
 
-To be written.
+Researchers, please note that even though :doc:`Kwant is Free Software
+<license>`, scientific integrity obliges to give appropriate credit.  If you
+write a scientific paper whose results have been obtained with the help of
+Kwant, please acknowledge the work of the :doc:`people that have developed it
+<authors>`.
+
+Reference to Kwant paper to be added.

INSTALL

-================
-Installing Kwant
-================
+=========================
+Installation instructions
+=========================
 
 Kwant can be installed either using some prepared packages (on Linux, Mac OSX,
 and Windows), or it can be built and installed from source.
@@ -11,9 +11,9 @@ will also allow them to customize Kwant to use certain optimized versions of
 libraries.
 
 
-******************************
-Installing Kwant from packages
-******************************
+************************
+Installing from packages
+************************
 
 Mac OSX
 =======
@@ -157,9 +157,9 @@ Notes
   though.
 
 
-*****************************************
-Building and installing Kwant from source
-*****************************************
+***********************************
+Building and installing from source
+***********************************
 
 Prerequisites
 =============

doc/source/acknowledgements.rst

-.. include:: ../../ACKNOWLEDGEMENTS

doc/source/authors.rst

-.. include:: ../../AUTHORS

doc/source/index.rst

@@ -2,23 +2,10 @@
 Kwant documentation
 ===================
 
-.. include:: ../../README
-   :end-before: See also the files
-
-Researchers, please note that even though :doc:`Kwant is Free Software
-<license>`, scientific integrity obliges to give appropriate credit.  If you
-write a scientific paper whose results have been obtained with the help of
-Kwant, please :doc:`acknowledge <acknowledgements>` the work of the :doc:`people
-that have developed it <authors>`.
-
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   license
-   authors
-   acknowledgements
-   whatsnew/index
-   install
+   pre/index
    tutorial/index
    reference/index
 

doc/source/install.rst

-.. include:: ../../INSTALL

doc/source/license.rst

-.. include:: ../../LICENSE

doc/source/pre/acknowledgements.rst

+.. include:: ../../../ACKNOWLEDGEMENTS

doc/source/pre/authors.rst

+.. include:: ../../../AUTHORS

doc/source/pre/index.rst

+Preliminaries
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   whatsnew/index
+   install
+   authors
+   acknowledgements
+   license

doc/source/pre/install.rst

+.. include:: ../../../INSTALL

doc/source/pre/license.rst

+.. include:: ../../../LICENSE

doc/source/whatsnew/0.2.rst → doc/source/pre/whatsnew/0.2.rst

@@ -28,7 +28,7 @@ the same time it is able to take advantage of more than 2 GiB of RAM.
 
 New tutorial dealing with superconductivity
 -------------------------------------------
-:doc:`../tutorial/tutorial5`
+:doc:`../../tutorial/tutorial5`
 
 New `~kwant.plotter` module
 ---------------------------
@@ -71,7 +71,7 @@ Band structure functionality has been moved
 The functionality that used to be provided by the method ``energies`` of
 `kwant.system.InfiniteSystem` has been moved to the `kwant.physics` package.
 See the documentation of `kwant.physics.Bands` and
-:doc:`../tutorial/tutorial3`.
+:doc:`../../tutorial/tutorial3`.
 
 Calculation of the local density of states
 ------------------------------------------

doc/source/whatsnew/1.0.rst → doc/source/pre/whatsnew/1.0.rst

@@ -80,7 +80,7 @@ actually different lattices. This often led to confusions in more convoluted
 use cases, so this behavior was changed. Now two site families created with the
 same parameters are actually indistinguishable by Kwant. If it is desired to
 make two site families which have the same geometry, but mean different things,
-as for instance in :doc:`../tutorial/tutorial5`, then the `name` argument has
+as for instance in :doc:`../../tutorial/tutorial5`, then the `name` argument has
 to be used when creating a lattice, e.g. `a = kwant.lattice.square(name='a');
 b = kwant.lattice.square(name='b')`.
 

doc/source/reference/index.rst

-Reference guide
-===============
+Essential modules
+=================
 
-Core modules of Kwant, appearing in the order of decreasing
-end-user relevance.
+The following modules make up the part of kwant that is most visible to its
+users.
 
 .. toctree::
    :maxdepth: 1
@@ -13,20 +13,28 @@ end-user relevance.
    kwant.plotter
    kwant.solvers
    kwant.physics
-   kwant.system
 
-Miscellaneous modules for special applications.
+Modules mainly for internal use
+===============================
+
+The following modules contain functionality that is most often used only
+internally by Kwant itself or by advanced users.
 
 .. toctree::
    :maxdepth: 1
 
-   kwant.digest
-   kwant.rmt
+   kwant.system
+   kwant.graph
+   kwant.linalg
+
+Miscellaneous modules
+=====================
 
-Modules mainly for internal use.
+The following modules are not part of the core of Kwant.  They are, however,
+very useful for certain applications.
 
 .. toctree::
    :maxdepth: 1
 
-   kwant.graph
-   kwant.linalg
+   kwant.digest
+   kwant.rmt

doc/source/reference/kwant.solvers.rst

@@ -7,10 +7,10 @@ Overview
 Kwant offers several modules for computing the solutions to quantum transport
 problems, the so-called solvers. Each of these solvers may use different
 internal algorithms and/or depend on different external libraries.  If the
-libraries needed by one solver are not installed, trying to import it will
-raise an ``ImportError`` exception.  The :doc:`Installation instructions
-<../install>` list all the libraries that are required or can be used by Kwant
-and its solvers.
+libraries needed by one solver are not installed, trying to import it will raise
+an ``ImportError`` exception.  The :doc:`Installation instructions
+<../pre/install>` list all the libraries that are required or can be used by
+Kwant and its solvers.
 
 
 :mod:`kwant.solvers.default` -- The default solver
@@ -68,7 +68,7 @@ default solver are listed in the documentation of each module.
    kwant.solvers.sparse
    kwant.solvers.mumps
 
-For Kwant-experts: detail of the internal structure of a solver
+For Kwant experts: detail of the internal structure of a solver
 ---------------------------------------------------------------
 
 Each solver module (except the default one) contains a class ``Solver`` (e.g.