Clean up documentation and help around json options

1 files changed, 28 insertions, 16 deletions

diff --git a/manual/cli.rst b/manual/cli.rst
index 54966a18..7dd955c4 100644
--- a/manual/cli.rst
+++ b/manual/cli.rst
@@ -14,7 +14,7 @@
    :qpdf:ref:`--option`. They also appear in an index.
 
    Note: 2022-01-22: because short help text is used in the "schema"
-   json object for QPDFJob json, we can't end short text with a ``)``
+   JSON object for QPDFJob JSON, we can't end short text with a ``)``
    character since doing so would cause ``)"`` to appear in the string
    literal. We use the R"(...)" syntax for these literals, and that
    looks like an end delimiter. While the C++ spec allows
@@ -163,10 +163,11 @@ Related Options
    .. help: job JSON file
 
       Specify the name of a file whose contents are expected to
-      contain a QPDFJob json file.
+      contain a QPDFJob JSON file. Run qpdf --job-json-help for a
+      description of the JSON input file format.
 
    Specify the name of a file whose contents are expected to contain a
-   QPDFJob json file. QXXXQ ref.  This file is read and treated as if
+   QPDFJob JSON file. QXXXQ ref.  This file is read and treated as if
    the equivalent command-line arguments were supplied. It can be
    mixed freely with other options.
 
@@ -3138,31 +3139,41 @@ Related Options
 
 .. qpdf:option:: --json[=version]
 
-   .. help: show file in json format
+   .. help: show file in JSON format
 
       Generate a JSON representation of the file. This is described in
       depth in the JSON section of the manual. "version" may be a
-      specific version or "latest".
+      specific version or "latest". Run qpdf --json-help for a
+      description of the generated JSON object.
 
    Generate a JSON representation of the file. This is described in
    depth in :ref:`json`. The version parameter can be used to specify
-   which json version should be output. The only supported value is
-   ``1``, but it's possible that a new json output version will be
-   added in a future version. You can also specify ``latest`` to use
-   the latest json version. For backward compatibility, the default
-   value is ``1``.
+   which version of the qpdf JSON format should be output. The only
+   supported value is ``1``, but it's possible that a new JSON output
+   version will be added in a future version. You can also specify
+   ``latest`` to use the latest JSON version. For backward
+   compatibility, the default value is ``1``. Use the
+   :qpdf:ref:`--json-help` option to get a description of the JSON
+   object.
 
 .. qpdf:option:: --json-help
 
-   .. help: show format of json output
+   .. help: show format of JSON output
 
-      Describe the format of the JSON output.
+      Describe the format of the JSON output by writing to standard
+      output a JSON object with the same keys and with values
+      containing descriptive text.
 
-   Describe the format of the JSON output.
+   Describe the format of the JSON output by writing to standard
+   output a JSON object with the same structure with the same keys as
+   the JSON generated by qpdf. In the output written by
+   ``--json-help``, each key's value is a description of the key. The
+   specific contract guaranteed by qpdf in its JSON representation is
+   explained in more detail in the :ref:`json`.
 
 .. qpdf:option:: --json-key=key
 
-   .. help: limit which keys are in json output
+   .. help: limit which keys are in JSON output
 
       This option is repeatable. If given, only the specified
       top-level keys will be included in the JSON output. Otherwise,
@@ -3170,7 +3181,8 @@ Related Options
 
    This option is repeatable. If given, only the specified top-level
    keys will be included in the JSON output. Otherwise, all keys will
-   be included.
+   be included. ``version`` and ``parameters`` will always appear in
+   the output.
 
 .. qpdf:option:: --json-object={trailer|obj[,gen]}
 
@@ -3186,7 +3198,7 @@ Related Options
 
 .. qpdf:option:: --job-json-help
 
-   .. help: show format of job json
+   .. help: show format of job JSON
 
       Describe the format of the QPDFJob JSON input.