Minor doc improvements

Various improvements suggested on the mailing list in March by Antoni Bella Perez. I made some minor edits to his patch to account for changes made to the docs since then. I also think I failed to mark Toni as the author of the commit of his patch - I don't know if that is possible to fix at this point.