diff options
| -rw-r--r-- | cSpell.json | 4 | ||||
| -rw-r--r-- | job.sums | 4 | ||||
| -rw-r--r-- | libqpdf/JSON.cc | 11 | ||||
| -rw-r--r-- | libqpdf/JSONHandler.cc | 10 | ||||
| -rw-r--r-- | libqpdf/qpdf/auto_job_help.hh | 71 | ||||
| -rw-r--r-- | libtests/json.cc | 2 | ||||
| -rw-r--r-- | libtests/json_handler.cc | 1 | ||||
| -rw-r--r-- | libtests/libtests.testcov | 2 | ||||
| -rw-r--r-- | manual/cli.rst | 219 | ||||
| -rw-r--r-- | qpdf/test_driver.cc | 1 |
10 files changed, 175 insertions, 150 deletions
diff --git a/cSpell.json b/cSpell.json index 144f394e..aacb3051 100644 --- a/cSpell.json +++ b/cSpell.json @@ -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 diff --git a/libqpdf/JSON.cc b/libqpdf/JSON.cc index f70145a7..58476ff8 100644 --- a/libqpdf/JSON.cc +++ b/libqpdf/JSON.cc @@ -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& 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(); diff --git a/libqpdf/JSONHandler.cc b/libqpdf/JSONHandler.cc index 1d374e6a..28e97218 100644 --- a/libqpdf/JSONHandler.cc +++ b/libqpdf/JSONHandler.cc @@ -88,20 +88,20 @@ JSONHandler::handle(std::string const& 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)) diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh index b50025e4..62991284 100644 --- a/libqpdf/qpdf/auto_job_help.hh +++ b/libqpdf/qpdf/auto_job_help.hh @@ -328,9 +328,11 @@ ap.addOptionHelp("--underlay", "modification", "begin underlay options", R"(--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 diff --git a/libtests/json.cc b/libtests/json.cc index 754c2b3e..c37af0e8 100644 --- a/libtests/json.cc +++ b/libtests/json.cc @@ -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& obj, JSON& schema, unsigned long flags, static void test_schema() { + /* cSpell: ignore ptional ebra */ JSON schema = JSON::parse(R"( { "one": { diff --git a/libtests/json_handler.cc b/libtests/json_handler.cc index c1af238f..618395d5 100644 --- a/libtests/json_handler.cc +++ b/libtests/json_handler.cc @@ -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, diff --git a/libtests/libtests.testcov b/libtests/libtests.testcov index 444f15bb..3e4d63d0 100644 --- a/libtests/libtests.testcov +++ b/libtests/libtests.testcov @@ -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 diff --git a/manual/cli.rst b/manual/cli.rst index 1c283598..2a5d66db 100644 --- a/manual/cli.rst +++ b/manual/cli.rst @@ -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 diff --git a/qpdf/test_driver.cc b/qpdf/test_driver.cc index 0e5b47af..65b2038c 100644 --- a/qpdf/test_driver.cc +++ b/qpdf/test_driver.cc @@ -3128,6 +3128,7 @@ static void test_82(QPDF& 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")); |