WIP-Improved documentation

* Improves documentation by re-arranging its structure and
  introducing full discussion about performance merit of
  intbitset.

Signed-off-by: Samuele Kaplun <samuele.kaplun@cern.ch>
I think you don't even need the print statement there ...