merge various doco and code changes

Hi Hamish,
Hopefully I get the merge request correct this time - last time went to dansimau.

This branch has the changes I previously emailed about posted to gitorious but now I have a github account I'm putting through a merge request here.