From 5953116634660065510fa5892fcc42d0a3c5e725 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Mon, 31 Jan 2022 18:40:04 -0500 Subject: Clean up documentation and help around json options --- manual/cli.rst | 44 ++++++++++++++++++++++++++++---------------- manual/json.rst | 4 ++++ 2 files changed, 32 insertions(+), 16 deletions(-) (limited to 'manual') 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. diff --git a/manual/json.rst b/manual/json.rst index 5567794d..358cac90 100644 --- a/manual/json.rst +++ b/manual/json.rst @@ -175,3 +175,7 @@ be aware of: shown as not filterable by default, but they will be shown as filterable if you run :command:`qpdf --json --decode-level=all`. + +- The ``encrypt`` key's values will be populated for non-encrypted + files. Some values will be null, and others will have values that + apply to unencrypted files. -- cgit v1.2.3-70-g09d2