fix issue #20
Add proposed changes in issue #24 discussion
Update documentation