Simplify --json-output

Now --json-output just changes defaults. Allow output file with --json.

1 files changed, 45 insertions, 35 deletions

diff --git a/manual/cli.rst b/manual/cli.rst
index 809437b7..8383b87f 100644
--- a/manual/cli.rst
+++ b/manual/cli.rst
@@ -3194,7 +3194,16 @@ Related Options
    :qpdf:ref:`--json-help` option to get a description of the JSON
    object.
 
-.. qpdf:option:: --json-help
+   Starting with qpdf 11, when this option is specified, an output
+   file is optional (for backward compatibility) and defaults to
+   standard output. You may specify an output file to write the JSON
+   to a file rather than standard output.
+
+   Stream data is only included if :qpdf:ref:`--json-output` is
+   specified or if a value other than ``none`` is passed to
+   :qpdf:ref:`--json-stream-data`.
+
+.. qpdf:option:: --json-help[=version]
 
    .. help: show format of JSON output
 
@@ -3202,12 +3211,13 @@ Related Options
       output a JSON object with the same keys and with values
       containing descriptive text.
 
-   Describe the format of the JSON output by writing to standard
-   output a JSON object with the same structure 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`.
+   Describe the format of the corresponding version of JSON output by
+   writing to standard output a JSON object with the same structure 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`. The default version of
+   help is version ``2``, as with the :qpdf:ref:`--json` flag.
 
 .. qpdf:option:: --json-key=key
 
@@ -3233,11 +3243,9 @@ Related Options
       objects will be shown.
 
    This option is repeatable. If given, only specified objects will be
-   shown in the ``"objects"`` key of the JSON output. Otherwise, all
-   objects will be shown. For qpdf JSON version 1, this also affects
-   the ``"objectinfo"`` key, which is not present in version 2. This
-   option may be used with :qpdf:ref:`--json` and also with
-   :qpdf:ref:`--json-output`.
+   shown in the objects dictionary in the JSON output. Otherwise, all
+   objects will be shown. See :ref:`json` for details about the qpdf
+   JSON format.
 
 .. qpdf:option:: --json-stream-data={none|inline|file}
 
@@ -3281,28 +3289,30 @@ Related Options
 
 .. qpdf:option:: --json-output[=version]
 
-   .. help: serialize to JSON
+   .. help: apply defaults for JSON serialization
 
-      The output file will be qpdf JSON format at the given version.
-      "version" may be a specific version or "latest" (the default).
-      The only supported version is 2. See also --json-stream-data,
-      --json-stream-prefix, and --decode-level.
+      Implies --json=version. Changes default values for certain
+      options so that the JSON output written is the most faithful
+      representation of the original PDF and contains no additional
+      JSON keys. See also --json-stream-data, --json-stream-prefix,
+      and --decode-level.
 
-   The output file, instead of being a PDF file, will be a JSON file
-   in qpdf JSON format at the given version. ``version`` may be a
-   specific version or ``latest`` (the default). The only supported
-   version is 2. See also :qpdf:ref:`--json-stream-data` and
-   :qpdf:ref:`--json-stream-prefix`. This option also changes the
-   following defaults:
+   Implies :qpdf:ref:`--json` at the specified version. This option
+   changes several default values, all of which can be overridden by
+   specifying the stated option:
 
    - The default value for :qpdf:ref:`--json-stream-data` changes from
      ``none`` to ``inline``.
 
-   - The default decode level for stream data becomes ``none``, but you can
-     override it with :qpdf:ref:`--decode-level`.
+   - The default value for :qpdf:ref:`--decode-level` changes from
+     ``generalized`` to ``none``.
+
+   - By default, only the ``"qpdf"`` key is included in the JSON
+     output, but you can add additional keys with
+     :qpdf:ref:`--json-key`.
 
-   - Only the ``"qpdf"`` key is included in the JSON output, but you
-     can add additional keys with :qpdf:ref:`--json-key`.
+   - Excludes the ``"version"`` and ``"parameters"`` keys from the
+     JSON output.
 
    If you want to look at the contents of streams easily as you would
    in QDF mode (see :ref:`qdf`), you can use
@@ -3313,15 +3323,15 @@ Related Options
 
    .. help: input file is qpdf JSON
 
-      Treat the input file as a JSON file in qpdf JSON format as
-      written by qpdf --json-output. See the "qpdf JSON Format"
-      section of the manual for information about how to use this
-      option.
+      Treat the input file as a JSON file in qpdf JSON format. See the
+      "qpdf JSON Format" section of the manual for information about
+      how to use this option.
 
-   Treat the input file as a JSON file in qpdf JSON format as written
-   by ``qpdf --json-output``. The input file must be complete and
-   include all stream data. For information about converting between
-   PDF and JSON, please see :ref:`json`.
+   Treat the input file as a JSON file in qpdf JSON format. The input
+   file must be complete and include all stream data. The JSON version
+   must be at least 2. All top-level keys are ignored except for
+   ``"qpdf"``. For information about converting between PDF and JSON,
+   please see :ref:`json`.
 
 .. qpdf:option:: --update-from-json=qpdf-json-file