octoleo
/
qpdf
mirror of https://github.com/qpdf/qpdf.git
2
1
Fork 0
Code Issues Releases Wiki Activity

Clean up documentation and help around json options

This commit is contained in:
Jay Berkenbilt 2022-01-31 18:40:04 -05:00
parent 606420ab54
commit 5953116634
7 changed files with 51 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
ChangeLog
View File

@ -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
View File

@ -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

23
libqpdf/QPDFJob_argv.cc
View File

@ -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

16
libqpdf/qpdf/auto_job_help.hh
View File

@ -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.

4
libqpdf/qpdf/auto_job_schema.hh
View File

@ -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"

44
manual/cli.rst
View File

@ -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.

4
manual/json.rst
View File

@ -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.