mirror of
https://github.com/qpdf/qpdf.git
synced 2024-12-22 10:58:58 +00:00
Clean up documentation and help around json options
This commit is contained in:
Jay Berkenbilt
parent
606420ab54
commit
5953116634
@ -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.
|
||||
|
||||
|
||||
6
job.sums
6
job.sums
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user