Implement several requested new features and fix a bug in the documentation. 
Added an example to demonstrate these new features