This commit adds an example test file so it integrates nicely with Go's
example tooling.
This allows the example output to be tested as a part of running the
normal Go tests to help ensure it doesn't get out of date with the code.
It is also nice to have the examples in one place rather than repeating it
in doc.go and README.md.
Links and information about the examples have been included in README.md in
place of the examples and doc.go has been updated accordingly.
