more patches and documentation from @riban, see #466