many changes in doc: merge from Davide revision