adding an example and slight reformulations.  I originally started the PR
because the PyPI page had some wrong statements.  Then i saw it
was partially already fixed.  I went ahead anyway, hope it makes
sense to you.