RFR: 7903859: add more details to the top-level README.md file

[Jonathan Gibbons]

Please review a docs update, mostly correcting or adding details to the top-level README.md, but also taking this opportunity to add some details into the "man" page.

-------------

Commit messages:
 - CODETOOLS-7903859: add more details to the top-level README.md file

Changes: https://git.openjdk.org/apidiff/pull/24/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=24&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903859
  Stats: 71 lines in 2 files changed: 64 ins; 0 del; 7 mod
  Patch: https://git.openjdk.org/apidiff/pull/24.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/24/head:pull/24

PR: https://git.openjdk.org/apidiff/pull/24