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>
This is kind of detail that belongs to the Note section where we speak about maxelem and stuff.  It would be good if the beginning of the documentation is impactful.  (I'll comment elsewhere on the structure.)