More editorial changes from m-holger + spell check

Jay Berkenbilt
1 parent 0e909bab
Showing 10 changed files with 175 additions and 150 deletions
cSpell.json
job.sums
libqpdf/JSON.cc
libqpdf/JSONHandler.cc
libqpdf/qpdf/auto_job_help.hh
libtests/json.cc
libtests/json_handler.cc
libtests/libtests.testcov
manual/cli.rst
qpdf/test_driver.cc
@@ -11,7 +11,6 @@
     "afdh",
     "afdhph",
     "ageneration",
-    "agogo",
     "aitems",
     "annots",
     "aobjid",
@@ -64,6 +63,7 @@
     "coldwind",
     "colorspace",
     "conftest",
+    "copiable",
     "cout",
     "cphe",
     "cppflags",
@@ -71,6 +71,7 @@
     "cregex",
     "crnl",
     "csoe",
+    "cstr",
     "cxxflags",
     "cygwin",
     "dctdecode",
@@ -354,6 +355,7 @@
     "qpdfsystemerror",
     "qpdftokenizer",
     "qpdftypes",
+    "qpdfusage",
     "qpdfwriter",
     "qpdfx",
     "qpdfxrefentry",
@@ -8,8 +8,8 @@ include/qpdf/auto_job_c_pages.hh 931840b329a36ca0e41401190e04537b47f2867671a6643
 include/qpdf/auto_job_c_uo.hh 0585b7de459fa479d9e51a45fa92de0ff6dee748efc9ec1cedd0dde6cee1ad50
 job.yml 1590fd16fd17ed40db9aa56b6713c844cfd61b3a6d0441a3ccd122b7371c68e9
 libqpdf/qpdf/auto_job_decl.hh 9f79396ec459f191be4c5fe34cf88c265cf47355a1a945fa39169d1c94cf04f6
-libqpdf/qpdf/auto_job_help.hh 30dd97f36c6cd748fc53fcb8d864140e32274437ffdf12f609ed04150ad61858
+libqpdf/qpdf/auto_job_help.hh 7155be7c3212afb9d5033dfacd3456768931bb6e837a2079d2332cd5bdafa087
 libqpdf/qpdf/auto_job_init.hh 3b6323189480a7d782563c9d2b5bc29b8dcd19c6dcc89840b207e38cb503d3f1
 libqpdf/qpdf/auto_job_schema.hh 1c3b4b5488270f8d200ed345573e3a241f15baff6fb7e97ec3d044103b2546d9
 manual/_ext/qpdf.py e9ac9d6c70642a3d29281ee5ad92ae2422dee8be9306fb8a0bc9dba0ed5e28f3
-manual/cli.rst 1cf74ad0956e51e919287f9dc93574764510856f562333a195775407551958a2
+manual/cli.rst 5fd018a6b34cd1b42a278f7b9afef709b72f082a65a563e8d2d3e10ce8ebe31a
@@ -880,6 +880,7 @@ void JSONParser::getToken()
             break;
           case ls_backslash:
+            /* cSpell: ignore bfnrt */
             if (strchr("\\\"bfnrt", *p))
             {
                 lex_state = ls_string;
@@ -972,7 +973,7 @@ JSONParser::handleToken()
     }
     // Git string value
-    std::string svalue;
+    std::string s_value;
     if (lex_state == ls_string)
     {
         // Token includes the quotation marks
@@ -980,7 +981,7 @@ JSONParser::handleToken()
         {
             throw std::logic_error("JSON string length < 2");
         }
-        svalue = decode_string(value);
+        s_value = decode_string(value);
     }
     // Based on the lexical state and value, figure out whether we are
     // looking at an item or a delimiter. It will always be exactly
@@ -1057,7 +1058,7 @@ JSONParser::handleToken()
         break;
       case ls_string:
-        item = new JSON(JSON::makeString(svalue));
+        item = new JSON(JSON::makeString(s_value));
         break;
       case ls_backslash:
@@ -1223,7 +1224,7 @@ JSONParser::handleToken()
         {
           case ps_dict_begin:
           case ps_dict_after_comma:
-            this->dict_key = svalue;
+            this->dict_key = s_value;
             item = nullptr;
             next_state = ps_dict_after_key;
             break;
@@ -1297,7 +1298,7 @@ JSONParser::parse(std::string const&amp; s)
     }
     if (parser_state != ps_done)
     {
-        QTC::TC("libtests", "JSON parse preature EOF");
+        QTC::TC("libtests", "JSON parse premature EOF");
         throw std::runtime_error("JSON: premature end of input");
     }
     return stack.back();
@@ -88,20 +88,20 @@ JSONHandler::handle(std::string const&amp; path, JSON j)
     }
     bool handled = false;
     bool bvalue = false;
-    std::string svalue;
+    std::string s_value;
     if (this->m->h.null_handler && j.isNull())
     {
         this->m->h.null_handler(path);
         handled = true;
     }
-    if (this->m->h.string_handler && j.getString(svalue))
+    if (this->m->h.string_handler && j.getString(s_value))
     {
-        this->m->h.string_handler(path, svalue);
+        this->m->h.string_handler(path, s_value);
         handled = true;
     }
-    if (this->m->h.number_handler && j.getNumber(svalue))
+    if (this->m->h.number_handler && j.getNumber(s_value))
     {
-        this->m->h.number_handler(path, svalue);
+        this->m->h.number_handler(path, s_value);
         handled = true;
     }
     if (this->m->h.bool_handler && j.getBool(bvalue))
@@ -328,9 +328,11 @@ ap.addOptionHelp(&quot;--underlay&quot;, &quot;modification&quot;, &quot;begin underlay options&quot;, R&quot;(--un
 Underlay pages from another file on the output.
 Run qpdf --help=overlay-underlay for details.
 )");
-ap.addOptionHelp("--flatten-rotation", "modification", "remove rotation from page dictionary", R"(Rotate a page using content commands instead of page-level
-metadata. This can be useful if a broken PDF viewer fails to
-properly consider page rotation metadata.
+ap.addOptionHelp("--flatten-rotation", "modification", "remove rotation from page dictionary", R"(For each page that is rotated using the /Rotate key in the
+page's dictionary, remove the /Rotate key and implement the
+identical rotation semantics by modifying the page's contents.
+This can be useful if a broken PDF viewer fails to properly
+consider page rotation metadata.
 )");
 ap.addOptionHelp("--flatten-annotations", "modification", "push annotations into content", R"(--flatten-annotations=parameter
@@ -360,8 +362,6 @@ options:
   --oi-min-height
   --oi-min-area
   --keep-inline-images
-
-The --verbose flag is useful with this option.
 )");
 ap.addOptionHelp("--oi-min-width", "modification", "minimum width for --optimize-images", R"(--oi-min-width=width
@@ -616,35 +616,25 @@ for help with the page range syntax.
 ap.addHelpTopic("attachments", "work with embedded files", R"(It is possible to list, add, or delete embedded files (also known
 as attachments) and to copy attachments from other files. See help
 on individual options for details. Run qpdf --help=add-attachment
-for additional details about adding attachments.
-)");
-ap.addOptionHelp("--list-attachments", "attachments", "list embedded files", R"(Show the key and stream number for each embedded file. Combine
-with --verbose for more detailed information.
+for additional details about adding attachments. See also
+--help=--list-attachments and --help=--show-attachment.
 )");
-ap.addOptionHelp("--show-attachment", "attachments", "export an embedded file", R"(--show-attachment=key
-
-Write the contents of the specified attachment to standard
-output as binary data. Get the key with --list-attachments.
-)");
-ap.addOptionHelp("--add-attachment", "attachments", "start add attachment options", R"(--add-attachment file options --
+ap.addOptionHelp("--add-attachment", "attachments", "start add attachment options", R"(--add-attachment file [options] --
 The --add-attachment flag and its options may be repeated to add
 multiple attachments. Run qpdf --help=add-attachment for details.
 )");
-ap.addOptionHelp("--remove-attachment", "attachments", "remove an embedded file", R"(--remove-attachment=key
-
-Remove an embedded file using its key. Get the key with
---list-attachments.
-)");
-}
-static void add_help_6(QPDFArgParser& ap)
-{
-ap.addOptionHelp("--copy-attachments-from", "attachments", "start copy attachment options", R"(--copy-attachments-from file options --
+ap.addOptionHelp("--copy-attachments-from", "attachments", "start copy attachment options", R"(--copy-attachments-from file [options] --
 The --copy-attachments-from flag and its options may be repeated
 to copy attachments from multiple files. Run
 qpdf --help=copy-attachments for details.
 )");
+ap.addOptionHelp("--remove-attachment", "attachments", "remove an embedded file", R"(--remove-attachment=key
+
+Remove an embedded file using its key. Get the key with
+--list-attachments.
+)");
 ap.addHelpTopic("pdf-dates", "PDF date format", R"(When a date is required, the date should conform to the PDF date
 format specification, which is "D:yyyymmddhhmmssz" where "z" is
 either literally upper case "Z" for UTC or a timezone offset in
@@ -657,21 +647,24 @@ Examples:
 - D:20210207161528-05'00'   February 7, 2021 at 4:15:28 p.m.
 - D:20210207211528Z         February 7, 2021 at 21:15:28 UTC
 )");
+}
+static void add_help_6(QPDFArgParser& ap)
+{
 ap.addHelpTopic("add-attachment", "attach (embed) files", R"(The options listed below appear between --add-attachment and its
 terminating "--".
 )");
 ap.addOptionHelp("--key", "add-attachment", "specify attachment key", R"(--key=key
 Specify the key to use for the attachment in the embedded files
-table. It defaults to the last element of the attached file's
-filename.
+table. It defaults to the last element (basename) of the
+attached file's filename.
 )");
 ap.addOptionHelp("--filename", "add-attachment", "set attachment's displayed filename", R"(--filename=name
 Specify the filename to be used for the attachment. This is what
 is usually displayed to the user and is the name most graphical
 PDF viewers will use when saving a file. It defaults to the last
-element of the attached file's filename.
+element (basename) of the attached file's filename.
 )");
 ap.addOptionHelp("--creationdate", "add-attachment", "set attachment's creation date", R"(--creationdate=date
@@ -712,7 +705,7 @@ duplicate attachment keys. This affects the key only, not the
 file name.
 )");
 ap.addHelpTopic("inspection", "inspect PDF files", R"(These options provide tools for inspecting PDF files. When any of
-the options in this section are specified, no output file should be
+the options in this section are specified, no output file may be
 given.
 )");
 ap.addOptionHelp("--is-encrypted", "inspection", "silently test whether a file is encrypted", R"(Silently exit with a code indicating the file's encryption status:
@@ -743,15 +736,12 @@ user password if the owner password is given and the file was
 encrypted using older encryption formats that allow user
 password recovery.
 )");
-ap.addOptionHelp("--show-encryption-key", "inspection", "show key with --show-encryption", R"(When used with --show-encryption, causes the underlying
-encryption key to be displayed.
+ap.addOptionHelp("--show-encryption-key", "inspection", "show key with --show-encryption", R"(When used with --show-encryption or --check, causes the
+underlying encryption key to be displayed.
 )");
 ap.addOptionHelp("--check-linearization", "inspection", "check linearization tables", R"(Check to see whether a file is linearized and, if so, whether
 the linearization hint tables are correct.
 )");
-}
-static void add_help_7(QPDFArgParser& ap)
-{
 ap.addOptionHelp("--show-linearization", "inspection", "show linearization hint tables", R"(Check and display all data in the linearization hint tables.
 )");
 ap.addOptionHelp("--show-xref", "inspection", "show cross reference data", R"(Show the contents of the cross-reference table or stream (object
@@ -759,7 +749,10 @@ locations in the file) in a human-readable form. This is
 especially useful for files with cross-reference streams, which
 are stored in a binary format.
 )");
-ap.addOptionHelp("--show-object", "inspection", "show contents of an object", R"(--show-object=trailer|obj[,gen]
+}
+static void add_help_7(QPDFArgParser& ap)
+{
+ap.addOptionHelp("--show-object", "inspection", "show contents of an object", R"(--show-object={trailer|obj[,gen]}
 Show the contents of the given object. This is especially useful
 for inspecting objects that are inside of object streams (also
@@ -784,6 +777,14 @@ object and for each content stream associated with the page.
 ap.addOptionHelp("--with-images", "inspection", "include image details with --show-pages", R"(When used with --show-pages, also shows the object and
 generation numbers for the image objects on each page.
 )");
+ap.addOptionHelp("--list-attachments", "inspection", "list embedded files", R"(Show the key and stream number for each embedded file. Combine
+with --verbose for more detailed information.
+)");
+ap.addOptionHelp("--show-attachment", "inspection", "export an embedded file", R"(--show-attachment=key
+
+Write the contents of the specified attachment to standard
+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.
 )");
@@ -798,7 +799,7 @@ 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.
 )");
-ap.addOptionHelp("--json-object", "json", "restrict which objects are in JSON", R"(--json-object=trailer|obj[,gen]
+ap.addOptionHelp("--json-object", "json", "restrict which objects are in JSON", R"(--json-object={trailer|obj[,gen]}
 This option is repeatable. If given, only specified objects will
 be shown in the "objects" key of the JSON output. Otherwise, all
@@ -29,6 +29,7 @@ static void test_main()
     assert(jstr2.getString(value));
     assert(value == "a\tb");
     assert(! jstr2.getNumber(value));
+    /* cSpell: ignore jbool xavalue dvalue xdvalue */
     JSON jint = JSON::makeInt(16059);
     JSON jdouble = JSON::makeReal(3.14159);
     JSON jexp = JSON::makeNumber("2.1e5");
@@ -128,6 +129,7 @@ static void check_schema(JSON&amp; obj, JSON&amp; schema, unsigned long flags,
 static void test_schema()
 {
+    /* cSpell: ignore ptional ebra */
     JSON schema = JSON::parse(R"(
 {
   "one": {
@@ -99,6 +99,7 @@ static void test_all()
 {
     std::cout << "-- all --" << std::endl;
     auto h = make_all_handler();
+    /* cSpell: ignore phour */
     JSON j = JSON::parse(R"({
    "one": "potato",
    "two": 3.14,
@@ -70,7 +70,7 @@ JSON parse unexpected } 0
 JSON parse unexpected ] 0
 JSON parse unexpected : 0
 JSON parse unexpected , 0
-JSON parse preature EOF 0
+JSON parse premature EOF 0
 JSON parse null character 0
 JSON parse bad character 0
 JSON parse point after e 0
@@ -109,9 +109,10 @@ Password-protected files may be opened by specifying a password with
 :qpdf:ref:`--password`.
 All options other than help options (see :ref:`help-options`) require
-an input file. If inspection options (see :ref:`inspection-options`)
-or help options are given, an output file must not be given. Otherwise,
-an output file is required.
+an input file. If inspection or JSON options (see
+:ref:`inspection-options` and :ref:`json-options`) or help options are
+given, an output file must not be given. Otherwise, an output file is
+required.
 If :samp:`@filename` appears as a word anywhere in the command-line,
 it will be read line by line, and each line will be treated as a
@@ -246,9 +247,9 @@ Shell Completion
 You can enable bash completion with :command:`eval $(qpdf
 --completion-bash)` and zsh completion with :command:`eval $(qpdf
 --completion-zsh)`. If :command:`qpdf` is not in your path, you should
-invoke it above with an absolute path. If you invoke it with a
-relative path, it will warn you, and the completion won't work if
-you're in a different directory.
+use an absolute path to qpdf in the above invocation. If you invoke it
+with a relative path, it will warn you, and the completion won't work
+if you're in a different directory.
 :command:`qpdf` will use ``argv[0]`` to figure out where its
 executable is. This may produce unwanted results in some cases,
@@ -1439,9 +1440,11 @@ Related Options
    .. help: remove rotation from page dictionary
-      Rotate a page using content commands instead of page-level
-      metadata. This can be useful if a broken PDF viewer fails to
-      properly consider page rotation metadata.
+      For each page that is rotated using the /Rotate key in the
+      page's dictionary, remove the /Rotate key and implement the
+      identical rotation semantics by modifying the page's contents.
+      This can be useful if a broken PDF viewer fails to properly
+      consider page rotation metadata.
    For each page that is rotated using the ``/Rotate`` key in the
    page's dictionary, remove the ``/Rotate`` key and implement the
@@ -1564,7 +1567,7 @@ Related Options
    If a file contains interactive form fields and indicates that the
    appearances are out of date with the values of the form, this flag
    will regenerate appearances, subject to a few limitations. Note
-   that there is not usually a reason to do this, but it can be
+   that there is usually no reason to do this, but it can be
    necessary before using the :qpdf:ref:`--flatten-annotations`
    option. Here is a summary of the limitations.
@@ -1614,8 +1617,6 @@ Related Options
         --oi-min-area
         --keep-inline-images
-      The --verbose flag is useful with this option.
-
    This flag causes qpdf to recompress all images that are not
    compressed with DCT (JPEG) using DCT compression as long as doing
    so decreases the size in bytes of the image data and the image does
@@ -1661,9 +1662,8 @@ Related Options
       Prevent inline images from being considered by --optimize-images.
-   Prevent inline images from being included in image optimization.
-   This option has no effect when :qpdf:ref:`--optimize-images` is not
-   specified.
+   Prevent inline images from being included in image optimization
+   done by :qpdf:ref:`--optimize-images`.
 .. qpdf:option:: --remove-page-labels
@@ -1901,12 +1901,12 @@ Related Options
       encryption.
    Enable/disable extraction of text for accessibility to visually
-   impaired users. The qpdf library disregards this field when AES is used
-   with 128-bit encryption or when 256-bit encryption is used. You
-   should never disable accessibility unless you are explicitly doing
-   so for creating test files. The PDF spec says that conforming
-   readers should disregard this permission and always allow
-   accessibility.
+   impaired users. The default is to be fully permissive. The qpdf
+   library disregards this field when AES is used with 128-bit
+   encryption or when 256-bit encryption is used. You should never
+   disable accessibility unless you are explicitly doing so for
+   creating test files. The PDF spec says that conforming readers
+   should disregard this permission and always allow accessibility.
    This option is not available with 40-bit encryption.
@@ -1920,10 +1920,10 @@ Related Options
       unless --modify-other=n or --modify=none is also specified.
    Enable/disable modifying annotations including making comments and
-   filling in form fields. For 128-bit and 256-bit encryption, this
-   also enables editing, creating, and deleting form fields unless
-   :samp:`--modify-other=n` or :samp:`--modify=none` is also
-   specified.
+   filling in form fields. The default is to be fully permissive. For
+   128-bit and 256-bit encryption, this also enables editing,
+   creating, and deleting form fields unless :samp:`--modify-other=n`
+   or :samp:`--modify=none` is also specified.
 .. qpdf:option:: --assemble=[yn]
@@ -1933,7 +1933,7 @@ Related Options
       pages). This option is not available with 40-bit encryption.
    Enable/disable document assembly (rotation and reordering of
-   pages).
+   pages). The default is to be fully permissive.
    This option is not available with 40-bit encryption.
@@ -1945,7 +1945,7 @@ Related Options
       accessibility.
    Enable/disable text/graphic extraction for purposes other than
-   accessibility.
+   accessibility. The default is to be fully permissive.
 .. qpdf:option:: --form=[yn]
@@ -1956,7 +1956,8 @@ Related Options
       available with 40-bit encryption.
    Enable/disable whether filling form fields is allowed even if
-   modification of annotations is disabled.
+   modification of annotations is disabled. The default is to be fully
+   permissive.
    This option is not available with 40-bit encryption.
@@ -1972,7 +1973,8 @@ Related Options
    Enable/disable modifications not controlled by
    :qpdf:ref:`--assemble`, :qpdf:ref:`--annotate`, or
    :qpdf:ref:`--form`. ``--modify-other=n`` is implied by any of the
-   other :qpdf:ref:`--modify` options except for ``--modify=all``.
+   other :qpdf:ref:`--modify` options except for ``--modify=all``. The
+   default is to be fully permissive.
    This option is not available with 40-bit encryption.
@@ -1995,7 +1997,8 @@ Related Options
       none: --modify-other=n --annotate=n --form=n --assemble=n
    For 40-bit files, :samp:`{modify-opt}` may only be ``y`` or ``n``
-   and controls all aspects of document modification.
+   and controls all aspects of document modification. The default is
+   to be fully permissive.
    For 128-bit and 256-bit encryption, :samp:`{modify-opt}` values
    allow enabling and disabling levels of restriction in a manner
@@ -2058,10 +2061,11 @@ Related Options
       low: allow low-resolution printing only
       full: allow full printing (the default)
-   Control what kind of printing is allowed. For 40-bit encryption,
-   :samp:`{print-opt}` may only be ``y`` or ``n`` and enables or disables all
-   printing. For 128-bit and 256-bit encryption, :samp:`{print-opt}`
-   may have the following values:
+   Control what kind of printing is allowed. The default is to be
+   fully permissive. For 40-bit encryption, :samp:`{print-opt}` may
+   only be ``y`` or ``n`` and enables or disables all printing. For
+   128-bit and 256-bit encryption, :samp:`{print-opt}` may have the
+   following values:
    .. list-table:: :samp:`{print-opt}` Values
       :widths: 10 80
@@ -2118,9 +2122,9 @@ Related Options
    created in this way are insecure since they can be opened without a
    password, and restrictions will not be enforced. Users would
    ordinarily never want to create such files. If you are using qpdf
-   to intentionally created strange files for testing (a definite
-   valid use of qpdf!), this option allows you to create such insecure
-   files. This option is only available with 256-bit encryption.
+   to intentionally created strange files for testing (a valid use of
+   qpdf!), this option allows you to create such insecure files. This
+   option is only available with 256-bit encryption.
    See :ref:`pdf-passwords` for a more technical discussion of this
    issue.
@@ -2262,7 +2266,7 @@ Examples
      qpdf --empty --pages a.pdf b.pdf --password=x z-1 c.pdf 3,6
-- Scan a document with printing on both sides by scanning the fronts
+- Scan a document with double-sided printing by scanning the fronts
   into :file:`odd.pdf` and the backs into :file:`even.pdf`. Collate
   the results into :file:`all.pdf`. This takes the first page of
   :file:`odd.pdf`, the first page of :file:`even.pdf`, the second page
@@ -2462,7 +2466,8 @@ output. The ``--overlay`` and ``--underlay`` options work the same
 way, except underlay pages are drawn underneath the page to which they
 are applied, possibly obscured by the original page, and overlay files
 are drawn on top of the page to which they are applied, possibly
-obscuring the page. You can combine overlay and underlay.
+obscuring the page. You can combine overlay and underlay, but you can
+only specify each option at most one time.
 The default behavior of overlay and underlay is that pages are taken
 from the overlay/underlay file in sequence and applied to
@@ -2495,8 +2500,14 @@ and the ``--`` option. The following options are supported:
 Specify a page range that indicates which pages in the
 overlay/underlay file will be used for overlay or underlay. If not
-specified, all pages will be used. This can be left empty by omitting
-:samp:`{page-range}` if :qpdf:ref:`--repeat` is used.
+specified, all pages will be used. The "from" pages are used until
+they are exhausted, after which any pages specified with
+:qpdf:ref:`--repeat` are used. If you are using the
+:qpdf:ref:`--repeat` option, you can use ``--from=`` to provide an
+empty set of "from" pages.
+
+This Can be left empty by omitting
+:samp:`{page-range}` 
 .. qpdf:option:: --repeat=page-range
@@ -2549,40 +2560,17 @@ Embedded Files/Attachments
    It is possible to list, add, or delete embedded files (also known
    as attachments) and to copy attachments from other files. See help
    on individual options for details. Run qpdf --help=add-attachment
-   for additional details about adding attachments.
+   for additional details about adding attachments. See also
+   --help=--list-attachments and --help=--show-attachment.
 It is possible to list, add, or delete embedded files (also known as
-attachments) and to copy attachments from other files.
+attachments) and to copy attachments from other files. See also
+:qpdf:ref:`--list-attachments` and :qpdf:ref:`--show-attachment`.
 Related Options
 ~~~~~~~~~~~~~~~
-.. qpdf:option:: --list-attachments
-
-   .. help: list embedded files
-
-      Show the key and stream number for each embedded file. Combine
-      with --verbose for more detailed information.
-
-   Show the *key* and stream number for each embedded file. With
-   :qpdf:ref:`--verbose`, additional information, including preferred
-   file name, description, dates, and more are also displayed. The key
-   is usually but not always equal to the file name and is needed by
-   some of the other options.
-
-.. qpdf:option:: --show-attachment=key
-
-   .. help: export an embedded file
-
-      Write the contents of the specified attachment to standard
-      output as binary data. Get the key with --list-attachments.
-
-   Write the contents of the specified attachment to standard output
-   as binary data. The key should match one of the keys shown by
-   :qpdf:ref:`--list-attachments`. If this option is given more than
-   once, only the last attachment will be shown.
-
-.. qpdf:option:: --add-attachment file options --
+.. qpdf:option:: --add-attachment file [options] --
    .. help: start add attachment options
@@ -2596,6 +2584,21 @@ Related Options
    add multiple attachments. Please see :ref:`add-attachment` for
    additional details.
+.. qpdf:option:: --copy-attachments-from file [options] --
+
+   .. help: start copy attachment options
+
+      The --copy-attachments-from flag and its options may be repeated
+      to copy attachments from multiple files. Run
+      qpdf --help=copy-attachments for details.
+
+   This flag starts copy attachment options, which are used to copy
+   attachments from other files.
+
+   The ``--copy-attachments-from`` flag and its options may be
+   repeated to copy attachments from multiple files. Please see
+   :ref:`copy-attachments` for additional details.
+
 .. qpdf:option:: --remove-attachment=key
    .. help: remove an embedded file
@@ -2612,21 +2615,6 @@ Related Options
    the attachment key. This option may be repeated to remove multiple
    attachments.
-.. qpdf:option:: --copy-attachments-from file options --
-
-   .. help: start copy attachment options
-
-      The --copy-attachments-from flag and its options may be repeated
-      to copy attachments from multiple files. Run
-      qpdf --help=copy-attachments for details.
-
-   This flag starts copy attachment options, which are used to copy
-   attachments from other files.
-
-   The ``--copy-attachments-from`` flag and its options may be
-   repeated to copy attachments from multiple files. Please see
-   :ref:`copy-attachments` for additional details.
-
 .. _pdf-dates:
 PDF Date Format
@@ -2682,12 +2670,13 @@ These options are valid between :qpdf:ref:`--add-attachment` and ``--``.
    .. help: specify attachment key
       Specify the key to use for the attachment in the embedded files
-      table. It defaults to the last element of the attached file's
-      filename.
+      table. It defaults to the last element (basename) of the
+      attached file's filename.
    Specify the key to use for the attachment in the embedded files
    table. It defaults to the last element of the attached file's
-   filename.
+   filename. For example, if you say ``--add-attachment
+   /home/user/image.png``, the default key will be just ``image.png``.
 .. qpdf:option:: --filename=name
@@ -2696,12 +2685,14 @@ These options are valid between :qpdf:ref:`--add-attachment` and ``--``.
       Specify the filename to be used for the attachment. This is what
       is usually displayed to the user and is the name most graphical
       PDF viewers will use when saving a file. It defaults to the last
-      element of the attached file's filename.
+      element (basename) of the attached file's filename.
    Specify the filename to be used for the attachment. This is what is
    usually displayed to the user and is the name most graphical PDF
    viewers will use when saving a file. It defaults to the last
-   element of the attached file's filename.
+   element of the attached file's filename. For example, if you say
+   ``--add-attachment /home/user/image.png``, the default key will be
+   just ``image.png``.
 .. qpdf:option:: --creationdate=date
@@ -2807,11 +2798,11 @@ PDF Inspection
 .. help-topic inspection: inspect PDF files
    These options provide tools for inspecting PDF files. When any of
-   the options in this section are specified, no output file should be
+   the options in this section are specified, no output file may be
    given.
 These options provide tools for inspecting PDF files. When any of the
-options in this section are specified, no output file should be given.
+options in this section are specified, no output file may be given.
 Related Options
 ~~~~~~~~~~~~~~~
@@ -2898,12 +2889,12 @@ Related Options
    If a password is supplied with :qpdf:ref:`--password`, that
    password is used to open the file just as with any normal
    invocation of :command:`qpdf`. That means that using this option
-   with :qpdf:ref:`--password` option can be used to check the
-   correctness of the password. In that case, an exit status of ``3``
-   means the file works with the supplied password. This option is
-   mutually exclusive with :qpdf:ref:`--is-encrypted`. Both this
-   option and :qpdf:ref:`--is-encrypted` exit with status ``2`` for
-   non-encrypted files.
+   with :qpdf:ref:`--password` can be used to check the correctness of
+   the password. In that case, an exit status of ``3`` means the file
+   works with the supplied password. This option is mutually exclusive
+   with :qpdf:ref:`--is-encrypted`. Both this option and
+   :qpdf:ref:`--is-encrypted` exit with status ``2`` for non-encrypted
+   files.
 .. qpdf:option:: --check
@@ -2962,8 +2953,8 @@ Related Options
    .. help: show key with --show-encryption
-      When used with --show-encryption, causes the underlying
-      encryption key to be displayed.
+      When used with --show-encryption or --check, causes the
+      underlying encryption key to be displayed.
    When encryption information is being displayed, as when
    :qpdf:ref:`--check` or :qpdf:ref:`--show-encryption` is given, display the
@@ -3016,7 +3007,7 @@ Related Options
    reconstruction is performed, this option will show the information
    in the reconstructed table.
-.. qpdf:option:: --show-object=trailer|obj[,gen]
+.. qpdf:option:: --show-object={trailer|obj[,gen]}
    .. help: show contents of an object
@@ -3103,6 +3094,32 @@ Related Options
    When used with :qpdf:ref:`--show-pages`, also shows the object and
    generation numbers for the image objects on each page.
+.. qpdf:option:: --list-attachments
+
+   .. help: list embedded files
+
+      Show the key and stream number for each embedded file. Combine
+      with --verbose for more detailed information.
+
+   Show the *key* and stream number for each embedded file. With
+   :qpdf:ref:`--verbose`, additional information, including preferred
+   file name, description, dates, and more are also displayed. The key
+   is usually but not always equal to the file name and is needed by
+   some of the other options. See also :ref:`attachments`.
+
+.. qpdf:option:: --show-attachment=key
+
+   .. help: export an embedded file
+
+      Write the contents of the specified attachment to standard
+      output as binary data. Get the key with --list-attachments.
+
+   Write the contents of the specified attachment to standard output
+   as binary data. The key should match one of the keys shown by
+   :qpdf:ref:`--list-attachments`. If this option is given more than
+   once, only the last attachment will be shown. See also
+   :ref:`attachments`.
+
 .. _json-options:
 JSON Options
@@ -3149,7 +3166,7 @@ Related Options
    keys will be included in the JSON output. Otherwise, all keys will
    be included.
-.. qpdf:option:: --json-object=trailer|obj[,gen]
+.. qpdf:option:: --json-object={trailer|obj[,gen]}
    .. help: restrict which objects are in JSON
@@ -3128,6 +3128,7 @@ static void test_82(QPDF&amp; pdf, char const* arg2)
     assert(stream.isStreamOfType("/ObjStm"));
     assert(! stream.isStreamOfType("/Test"));
     assert(! pdf.getObjectByID(2,0).isStreamOfType("/Pages"));
+    /* cSpell: ignore Blaah Blaaah Blaaaah */
     auto array = QPDFObjectHandle::parse("[/Blah /Blaah /Blaaah]");
     assert(array.isOrHasName("/Blah"));
     assert(array.isOrHasName("/Blaaah"));