substantial update of the documentation (intermediate commit - not finished)