diff options
| -rw-r--r-- | ChangeLog | 3 | ||||
| -rw-r--r-- | job.sums | 6 | ||||
| -rw-r--r-- | libqpdf/QPDFJob_argv.cc | 23 | ||||
| -rw-r--r-- | libqpdf/qpdf/auto_job_help.hh | 16 | ||||
| -rw-r--r-- | libqpdf/qpdf/auto_job_schema.hh | 4 | ||||
| -rw-r--r-- | manual/cli.rst | 44 | ||||
| -rw-r--r-- | manual/json.rst | 4 |
7 files changed, 51 insertions, 49 deletions
@@ -1,5 +1,8 @@ 2022-01-31 Jay Berkenbilt <ejb@ql.org> + * Have --json-help just output the JSON object, leaving a + description to --help and the manual. + * Allow optional version number or "latest" as parameter to --json, allowing for future specification of json version. @@ -8,10 +8,10 @@ include/qpdf/auto_job_c_pages.hh 931840b329a36ca0e41401190e04537b47f2867671a6643 include/qpdf/auto_job_c_uo.hh 0585b7de459fa479d9e51a45fa92de0ff6dee748efc9ec1cedd0dde6cee1ad50 job.yml effc93a805fb74503be2213ad885238db21991ba3d084fbfeff01183c66cb002 libqpdf/qpdf/auto_job_decl.hh 9f79396ec459f191be4c5fe34cf88c265cf47355a1a945fa39169d1c94cf04f6 -libqpdf/qpdf/auto_job_help.hh 6297d355cb37a6183469962ed75d465d62f498a9a49d43cac7af0c9d013a9e1b +libqpdf/qpdf/auto_job_help.hh 6002f503368f319a3d717484ac39d1558f34e67989d442f394791f6f6f5f0500 libqpdf/qpdf/auto_job_init.hh c244e03e8b83ed7db732920f40aff0134e5f2e78a6edb9473ea4dd1934a8953e libqpdf/qpdf/auto_job_json_decl.hh c5e3fd38a3b0c569eb0c6b4c60953a09cd6bc7d3361a357a81f64fe36af2b0cf libqpdf/qpdf/auto_job_json_init.hh 3f86ce40931ca8f417d050fcd49104d73c1fa4e977ad19d54b372831a8ea17ed -libqpdf/qpdf/auto_job_schema.hh d2fb9344bb0ed9b60cfa5511e81bea1335ea12997df731db9572de46b1d7f0b2 +libqpdf/qpdf/auto_job_schema.hh 18a3780671d95224cb9a27dcac627c421cae509d59f33a63e6bda0ab53cce923 manual/_ext/qpdf.py e9ac9d6c70642a3d29281ee5ad92ae2422dee8be9306fb8a0bc9dba0ed5e28f3 -manual/cli.rst 280826695c13d69527f49ef3e9de89cb628dc55cdbf2ad1dba1606325874c20a +manual/cli.rst 35289dbf593085016a62249f760cdcad50d5cce76d799ea4acf5dff58b78679a diff --git a/libqpdf/QPDFJob_argv.cc b/libqpdf/QPDFJob_argv.cc index 66ae02a5..ed37dbce 100644 --- a/libqpdf/QPDFJob_argv.cc +++ b/libqpdf/QPDFJob_argv.cc @@ -158,28 +158,7 @@ ArgParser::argCopyright() void ArgParser::argJsonHelp() { - // Make sure the output looks right on an 80-column display. - // 1 2 3 4 5 6 7 8 - // 12345678901234567890123456789012345678901234567890123456789012345678901234567890 - std::cout - << "The json block below contains the same structure with the same keys as the" - << std::endl - << "json generated by qpdf. In the block below, the values are descriptions of" - << std::endl - << "the meanings of those entries. The specific contract guaranteed by qpdf in" - << std::endl - << "its json representation is explained in more detail in the manual. You can" - << std::endl - << "specify a subset of top-level keys when you invoke qpdf, but the \"version\"" - << std::endl - << "and \"parameters\" keys will always be present. Note that the \"encrypt\"" - << std::endl - << "key's values will be populated for non-encrypted files. Some values will" - << std::endl - << "be null, and others will have values that apply to unencrypted files." - << std::endl - << QPDFJob::json_out_schema_v1() - << std::endl; + std::cout << QPDFJob::json_out_schema_v1() << std::endl; } void diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh index 34c6aa8a..49ac3494 100644 --- a/libqpdf/qpdf/auto_job_help.hh +++ b/libqpdf/qpdf/auto_job_help.hh @@ -30,7 +30,8 @@ ap.addOptionHelp("--replace-input", "usage", "overwrite input with output", R"(U ap.addOptionHelp("--job-json-file", "usage", "job JSON file", R"(--job-json-file=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. )"); ap.addHelpTopic("exit-status", "meanings of qpdf's exit codes", R"(Meaning of exit codes: @@ -788,15 +789,18 @@ output as binary data. Get the key with --list-attachments. ap.addHelpTopic("json", "JSON output for PDF information", R"(Show information about the PDF file in JSON format. Please see the JSON chapter in the qpdf manual for details. )"); -ap.addOptionHelp("--json", "json", "show file in json format", R"(--json[=version] +ap.addOptionHelp("--json", "json", "show file in JSON format", R"(--json[=version] 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. )"); -ap.addOptionHelp("--json-help", "json", "show format of json output", R"(Describe the format of the JSON output. +ap.addOptionHelp("--json-help", "json", "show format of JSON output", R"(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. )"); -ap.addOptionHelp("--json-key", "json", "limit which keys are in json output", R"(--json-key=key +ap.addOptionHelp("--json-key", "json", "limit which keys are in JSON output", R"(--json-key=key This option is repeatable. If given, only the specified top-level keys will be included in the JSON output. Otherwise, @@ -808,7 +812,7 @@ 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. )"); -ap.addOptionHelp("--job-json-help", "json", "show format of job json", R"(Describe the format of the QPDFJob JSON input. +ap.addOptionHelp("--job-json-help", "json", "show format of job JSON", R"(Describe the format of the QPDFJob JSON input. )"); ap.addHelpTopic("testing", "options for testing or debugging", R"(The options below are useful when writing automated test code that includes files created by qpdf or when testing qpdf itself. diff --git a/libqpdf/qpdf/auto_job_schema.hh b/libqpdf/qpdf/auto_job_schema.hh index 21a6747a..ca9fc1e1 100644 --- a/libqpdf/qpdf/auto_job_schema.hh +++ b/libqpdf/qpdf/auto_job_schema.hh @@ -77,9 +77,9 @@ static constexpr char const* JOB_SCHEMA_DATA = R"({ "withImages": "include image details with showPages", "listAttachments": "list embedded files", "showAttachment": "export an embedded file", - "json": "show file in json format", + "json": "show file in JSON format", "jsonKey": [ - "limit which keys are in json output" + "limit which keys are in JSON output" ], "jsonObject": [ "limit which objects are in JSON" 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. |