Tidying while reading

Avoid deep indentation, use more levels of headings instead.
Some more doc tweaks
Tidying while reading

Indentation fixed on one section too.
Merge pull request #1461 from jean/master

Tidying while reading