some of the changes are unrelated to this branch, but they
were minor and I noticed while reviewing.

grammar improvements

remove unuseful shutdown examples

add some docbook formatting tags

commented out an empty TODO section.