installation-instructions.md

@@ -4,13 +4,14 @@
 
 Python modules are usually very easy to install, typically requiring nothing more that `pip install <package>` for basically any operating system. For `graph-tool`, however, the situation is different. This is because, in reality, `graph-tool` is a C++ library wrapped in Python, and it has many C++ dependencies such as [Boost](http://www.boost.org/), [CGAL](http://www.cgal.org/) and [expat](http://expat.sourceforge.net/), which are not installable via Python-only package management systems such as [pip](http://www.pip-installer.org/). Because the module lives between the C++ and Python worlds, its installation is done more like a C++ library rather than a typical python module. This means it inherits some of the complexities common of the C++ world that some Python users do not expect.
 
-The easiest way to get going is to use a package manager, for which the installation is fairly straightforward.  This is the case for some GNU/Linux distributions (Arch, Gentoo, Debian & Ubuntu) as well as for MacOS users using either [Macports](http://www.macports.org/) or [Homebrew](http://brew.sh/).
+The easiest way to get going is to use a package manager, for which the installation is fairly straightforward.  This is the case for some [GNU/Linux distributions](#gnulinux) (Arch, Gentoo, Debian & Ubuntu) as well as for [MacOS](#macos) users using either [Macports](http://www.macports.org/) or [Homebrew](http://brew.sh/).
 
-Alternatively, `graph-tool` can be installed from source, by manual compilation. The module uses the standard [GNU build system](https://en.wikipedia.org/wiki/GNU_Build_System) for this (i.e. `./configure; make; make install`), and users wishing to go on this route are recommended to familiarize themselves with it. An in-depth resource is the [Autotools Mythbuster](https://autotools.io/index.html).
+Alternatively, `graph-tool` can be installed from source, by [manual compilation](#manual-compilation). The module uses the standard [GNU build system](https://en.wikipedia.org/wiki/GNU_Build_System) for this (i.e. `./configure; make; make install`), and users wishing to go on this route are recommended to familiarize themselves with it. [Basic instructions](#manual-compilation) are given below,  and an in-depth resource is the [Autotools Mythbuster](https://autotools.io/index.html).
 
-# GNU/Linux
+# Installation via package managers
+## GNU/Linux
 
-## Arch
+### Arch
 
 [Packages for Arch](https://aur.archlinux.org/packages/python-graph-tool/) are available in the Arch User Repository. You can install it with yaourt:
 
@@ -23,7 +24,7 @@ yaourt -S python-graph-tool
 ```
 depending on the python version.
 
-## Gentoo
+### Gentoo
 
 An ebuild for graph-tool is included in the default [Gentoo](https://www.gentoo.org/) repository. Just do
 
@@ -32,7 +33,7 @@ emerge graph-tool
 ```
 to install it.
 
-## Debian & Ubuntu
+### Debian & Ubuntu
 
 For [Debian](http://www.debian.org/), add the following lines to your `/etc/apt/sources.list`,
 
@@ -81,10 +82,8 @@ sub   4096R/1A7ECE03 2013-10-17 [expires: 2018-10-16]
 sub   4096R/23F08CAF 2013-10-17 [expires: 2018-10-16]
 ```
 
-<a name="macos"></a>
-
-# MacOS X
-## Macports
+## MacOS X
+### Macports
 
 A portfile is available for installation in MacOS X systems with [Macports](http://www.macports.org/). It is included in the [standard macports list](http://www.macports.org/ports.php?by=name&substr=graph-tool). Just run the following command to install it:
 
@@ -92,7 +91,7 @@ A portfile is available for installation in MacOS X systems with [Macports](http
 port install py-graph-tool
 ```
 
-## Homebrew
+### Homebrew
 
 With [Homebrew](http://brew.sh/) the installation is also straightforward, since a formula for it is included in the "science" list:
 ```
@@ -101,7 +100,7 @@ brew install graph-tool
 ```
 If you encounter an error installing graph-tool via Macports or Homebrew, please file a bug report via each respective project, not to graph-tool directly.
 
-#### Compiler choice in MacOS X
+##### Compiler choice in MacOS X
 
 TL;DR : Just use [clang](http://clang.llvm.org/) for everything.
 
@@ -111,6 +110,8 @@ In an ideal world, the correct version should be the latest one from the "stock"
 
 (If possible, a much better option would be to use a less [defective](http://www.defectivebydesign.org/apple) platform in the first place.)
 
+---------------------------------------
+
 # Manual compilation
 
 Graph-tool was tested extensively only on