RFR: 7903876: Improve the man page, with (more) examples [v2]

[Jonathan Gibbons]

> Please review an update to the main documentation page for the `apidiff` tool. The updates are primarily clarifications and examples, intended to reduce some of the recent confusion about using the tool.   As well as clarification and examples throughout the page, two more full examples are given at the end. These examples have been tested with scripts.  They are meant to be indicative of what one might use to create a diff report for a CSR submission. 
> 
> The generated HTML for the page can be seen here: https://cr.openjdk.org/~jjg/7903876/doc/apidiff.html
> 
> For the record, the scripts used to test the examples are as follows:
> 
> 
> *** play/apidiff-examples/apidiff-1.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline \
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release  \
>     --include java.compiler/** \
>     --output-directory build/apidiff
> 
> *** play/apidiff-examples/apidiff-2.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline --label "The baseline for the changes"\
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release --label "Add SourceVersion.RELEASE_24" \
>     --include java.compiler/** \
>     --output-directory build/apidiff \
>     --compare-api-descriptions true \
>     --jdk-docs docs \
>     --info-text top="This proposal is not yet final" \
>     --title "Diffs for JDK-8330183 CSR" \
>     --description "Generated by $USER at $(date -u)"

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  add note about quoting patterns, and other clarifications

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/28/files
  - new: https://git.openjdk.org/apidiff/pull/28/files/22ccba28..3d316243

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=apidiff&pr=28&range=01
 - incr: https://webrevs.openjdk.org/?repo=apidiff&pr=28&range=00-01

  Stats: 6 lines in 1 file changed: 3 ins; 0 del; 3 mod
  Patch: https://git.openjdk.org/apidiff/pull/28.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/28/head:pull/28

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