minor docs editing/examples improvement
Merge branch 'devel' into release-0.5.8