Introductory README/type/stuff rejigger based on pilot feedback. / Fixing minor test/demo logging problem. / Minor API tweak. / Comment typo, accuracy fix. / Minor manual tweak.

Introductory README/type/stuff rejigger based on pilot feedback. / Fixing minor test/demo logging problem. / Minor API tweak. / Comment typo, accuracy fix. / Minor manual tweak. #733