merge in improvments from Stephano
example and more documentation