Clean up documentation and help around json options

Jay Berkenbilt
1 parent 606420ab
Showing 7 changed files with 51 additions and 49 deletions
ChangeLog
job.sums
libqpdf/QPDFJob_argv.cc
libqpdf/qpdf/auto_job_help.hh
libqpdf/qpdf/auto_job_schema.hh
manual/cli.rst
manual/json.rst
 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
@@ -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(&quot;--replace-input&quot;, &quot;usage&quot;, &quot;overwrite input with output&quot;, R&quot;(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&quot;({
   "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.