fix examples and improve documentation. Fixes #33