markdown-ify the README file
corrections to examples
preparing version 1.2.3