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

[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)"

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

Commit messages:
 - CODETOOLS-7903876: Improve the man page, with (more) examples
 - Merge remote-tracking branch 'upstream/master' into 7903876.update-man-page
 - Merge remote-tracking branch 'upstream/master' into 7903870.exit-status-docs
 - CODETOOLS-7903870: add info about return codes (exit codes) to man page

Changes: https://git.openjdk.org/apidiff/pull/28/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=28&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903876
  Stats: 199 lines in 3 files changed: 160 ins; 6 del; 33 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