diff options
author | Jay Berkenbilt <ejb@ql.org> | 2022-07-31 16:34:05 +0200 |
---|---|---|
committer | Jay Berkenbilt <ejb@ql.org> | 2022-07-31 22:23:17 +0200 |
commit | 5f4224f31a500452a4f97f36ed57351b41ca0114 (patch) | |
tree | be355db5a4fcc8334410baf76c7eb1330578faa8 /manual/cli.rst | |
parent | 80acfc3826704064db8cc2f6af0c338b3aa557e7 (diff) | |
download | qpdf-5f4224f31a500452a4f97f36ed57351b41ca0114.tar.zst |
Simplify --json-output
Now --json-output just changes defaults. Allow output file with --json.
Diffstat (limited to 'manual/cli.rst')
-rw-r--r-- | manual/cli.rst | 80 |
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 |