Automated changes for --set-page-labels

This commit contains the changes from generate_auto_job based on
manual changes from the previous commit.

include/qpdf/auto_job_c_set_page_labels.hh

@@ -0,0 +1,7 @@
+//
+// This file is automatically generated by generate_auto_job.
+// Edits will be automatically overwritten if the build is
+// run in maintainer mode.
+//
+// clang-format off
+//

job.sums

@@ -7,14 +7,14 @@ include/qpdf/auto_job_c_enc.hh 28446f3c32153a52afa239ea40503e6cc8ac2c026813526a3
 include/qpdf/auto_job_c_main.hh dbfc221d1533120d1aa9c361d8d2483dea5fcb1c0fd95144d98d305e64ed32a6
 include/qpdf/auto_job_c_pages.hh b3cc0f21029f6d89efa043dcdbfa183cb59325b6506001c18911614fe8e568ec
 include/qpdf/auto_job_c_uo.hh ae21b69a1efa9333050f4833d465f6daff87e5b38e5106e49bbef5d4132e4ed1
-job.yml 4f89fc7b622df897d30d403d8035aa36fc7de8d8c43042c736e0300d904cb05c
-libqpdf/qpdf/auto_job_decl.hh 9c6f701c29f3f764d620186bed92685a2edf2e4d11e4f4532862c05470cfc4d2
-libqpdf/qpdf/auto_job_help.hh ea0d0cdebeb190d305bd5f9bca85a4430dbcfa0881ac9be839216b878765b379
-libqpdf/qpdf/auto_job_init.hh b4c2b3724fba61f1206fd3bae81951636852592f67a63ef9539839c2c5995065
-libqpdf/qpdf/auto_job_json_decl.hh 06caa46eaf71db8a50c046f91866baa8087745a9474319fb7c86d92634cc8297
-libqpdf/qpdf/auto_job_json_init.hh f5acb9aa103131cb68dec0e12c4d237a6459bdb49b24773c24f0c2724a462b8f
-libqpdf/qpdf/auto_job_schema.hh b53c006fec2e75b1b73588d242d49a32f7d3db820b1541de106c5d4c27fbb4d9
+job.yml 8ad309ac41520b34692bcf22fd5c2ef4810ff69562aed606bd57df7bf589bc43
+libqpdf/qpdf/auto_job_decl.hh 1e8d73891bd1f0b5df5a5ca7405fb76d2d0fd024941b8c1b86489f1b5f9c5772
+libqpdf/qpdf/auto_job_help.hh 8c172913920a5273e04dc4d2059f2d78fc475960ac1738271357056beb02dd27
+libqpdf/qpdf/auto_job_init.hh ea272fd6a6a5e4d23cabd70a7b7d5ecc543b6304008c656dcba2d353d378efc2
+libqpdf/qpdf/auto_job_json_decl.hh 10ffb0d0e5ca09809a5d5d78f66dee393dfd2653a23441436465fd5ace151880
+libqpdf/qpdf/auto_job_json_init.hh 9c3839877ab3b15a47e92086f0b5616da33fd4970538cc423d3b0a7ff33ce66a
+libqpdf/qpdf/auto_job_schema.hh a882939b202d48ad1c0751c094f671ad7aad0fc04c3a4446ad83675db365c8a2
 manual/_ext/qpdf.py 6add6321666031d55ed4aedf7c00e5662bba856dfcd66ccb526563bffefbb580
-manual/cli.rst d75ae0584df2217827d6663da1a83bfa78e70599156ef2ca9cfb1236833ffd22
-manual/qpdf.1 738dc9b732ad4c880d034b99f957077628fde1d0006943aaf813e98f8e2f9635
+manual/cli.rst 38ff5e0e3a6bc01eab0b7d9f3fd22bfe4ec90ad5dcd48ba8be8412177c7bbf61
+manual/qpdf.1 c89ac263ffb697c7c1f6233fa54bd6403a455a989b550f78868c284947d707a3
 manual/qpdf.1.in 436ecc85d45c4c9e2dbd1725fb7f0177fb627179469f114561adf3cb6cbb677b

libqpdf/qpdf/auto_job_decl.hh

@@ -13,6 +13,7 @@ static constexpr char const* O_256_BIT_ENCRYPTION = "256-bit encryption";
 static constexpr char const* O_UNDERLAY_OVERLAY = "underlay/overlay";
 static constexpr char const* O_ATTACHMENT = "attachment";
 static constexpr char const* O_COPY_ATTACHMENT = "copy attachment";
+static constexpr char const* O_SET_PAGE_LABELS = "set page labels";
 
 void argVersion();
 void argCopyright();
@@ -27,6 +28,7 @@ void argEncrypt();
 void argOverlay();
 void argPages();
 void argReplaceInput();
+void argSetPageLabels();
 void argUnderlay();
 void argPagesPositional(std::string const&);
 void argPagesPassword(std::string const&);
@@ -45,3 +47,5 @@ void argAttPositional(std::string const&);
 void argEndAttachment();
 void argCopyAttPositional(std::string const&);
 void argEndCopyAttachment();
+void argPageLabelsPositional(std::string const&);
+void argEndSetPageLabels();

libqpdf/qpdf/auto_job_help.hh

@@ -402,6 +402,41 @@ ap.addOptionHelp("--keep-inline-images", "modification", "exclude inline images
 )");
 ap.addOptionHelp("--remove-page-labels", "modification", "remove explicit page numbers", R"(Exclude page labels (explicit page numbers) from the output file.
 )");
+ap.addOptionHelp("--set-page-labels", "modification", "number pages for the entire document", R"(--set-page-labels label-spec ... --
+
+Set page labels (explicit page numbers) for the entire file.
+Each label-spec has the form
+
+first-page:[type][/start[/prefix]]
+
+where
+
+- "first-page" represents a sequential page number using the
+  same format as page ranges: a number, a number preceded by "r"
+  to indicate counting from the end, or "z" indicating the last
+  page
+- "type" is one of
+  - D: Arabic numerals (digits)
+  - A: Upper-case alphabetic characters
+  - a: Lower-case alphabetic characters
+  - R: Upper-case Roman numerals
+  - r: Lower-case Roman numerals
+  - omitted: the page number does not appear, though the prefix,
+    if specified will still appear
+- "prefix"` may be any string and is prepended to each page
+  label
+
+A given page label spec causes pages to be numbered according to
+that scheme starting with first-page and continuing until the
+next label spec or the end of the document. If you want to omit
+numbering starting at a certain page, you can use first-page: as
+the spec.
+
+Example: "1:r 5:D" would number the first four pages i through
+iv, then the remaining pages with Arabic numerals starting with
+1 and continuing sequentially until the end of the document. For
+additional examples, please consult the manual.
+)");
 ap.addHelpTopic("encryption", "create encrypted files", R"(Create encrypted files. Usage:
 
 --encrypt \
@@ -485,13 +520,13 @@ ap.addOptionHelp("--user-password", "encryption", "specify user password", R"(--
 
 Set the user password of the encrypted file.
 )");
+}
+static void add_help_5(QPDFArgParser& ap)
+{
 ap.addOptionHelp("--owner-password", "encryption", "specify owner password", R"(--owner-password=owner-password
 
 Set the owner password of the encrypted file.
 )");
-}
-static void add_help_5(QPDFArgParser& ap)
-{
 ap.addOptionHelp("--bits", "encryption", "specify encryption key length", R"(--bits={48|128|256}
 
 Specify the encryption key length. For best security, always use
@@ -665,15 +700,15 @@ the destination pages. See qpdf --help=page-ranges for help
 with the page range syntax. The page range may be omitted
 if --repeat is used.
 )");
+}
+static void add_help_6(QPDFArgParser& ap)
+{
 ap.addOptionHelp("--repeat", "overlay-underlay", "overlay/underlay pages to repeat", R"(--repeat=page-range
 
 Specify pages from the overlay/underlay that are repeated after
 "from" pages have been exhausted. See qpdf --help=page-ranges
 for help with the page range syntax.
 )");
-}
-static void add_help_6(QPDFArgParser& ap)
-{
 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
@@ -782,6 +817,9 @@ ap.addOptionHelp("--requires-password", "inspection", "silently test a file's pa
 2: the file is not encrypted
 3: the file is encrypted, and correct password (if any) has been supplied
 )");
+}
+static void add_help_7(QPDFArgParser& ap)
+{
 ap.addOptionHelp("--check", "inspection", "partially check whether PDF is valid", R"(Check the structure of the PDF file as well as a number of other
 aspects of the file, and write information about the file to
 standard output. Note that qpdf does not perform any validation
@@ -789,9 +827,6 @@ of the actual PDF page content or semantic correctness of the
 PDF file. It merely checks that the PDF file is syntactically
 valid. See also qpdf --help=exit-status.
 )");
-}
-static void add_help_7(QPDFArgParser& ap)
-{
 ap.addOptionHelp("--show-encryption", "inspection", "information about encrypted files", R"(Show document encryption parameters. Also show the document's
 user password if the owner password is given and the file was
 encrypted using older encryption formats that allow user
@@ -872,6 +907,9 @@ 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.
 )");
+}
+static void add_help_8(QPDFArgParser& ap)
+{
 ap.addOptionHelp("--json-stream-data", "json", "how to handle streams in json output", R"(--json-stream-data={none|inline|file}
 
 When used with --json, this option controls whether streams in
@@ -883,9 +921,6 @@ object number. The prefix can be overridden with
 when --json-output is specified, in which case the default is
 "inline".
 )");
-}
-static void add_help_8(QPDFArgParser& ap)
-{
 ap.addOptionHelp("--json-stream-prefix", "json", "prefix for json stream data files", R"(--json-stream-prefix=file-prefix
 
 When used with --json-stream-data=file, --json-stream-data=file-prefix

libqpdf/qpdf/auto_job_init.hh

@@ -73,6 +73,7 @@ this->ap.addBare("replace-input", b(&ArgParser::argReplaceInput));
 this->ap.addBare("report-memory-usage", [this](){c_main->reportMemoryUsage();});
 this->ap.addBare("requires-password", [this](){c_main->requiresPassword();});
 this->ap.addBare("remove-restrictions", [this](){c_main->removeRestrictions();});
+this->ap.addBare("set-page-labels", b(&ArgParser::argSetPageLabels));
 this->ap.addBare("show-encryption", [this](){c_main->showEncryption();});
 this->ap.addBare("show-encryption-key", [this](){c_main->showEncryptionKey();});
 this->ap.addBare("show-linearization", [this](){c_main->showLinearization();});
@@ -180,3 +181,5 @@ this->ap.registerOptionTable("copy attachment", b(&ArgParser::argEndCopyAttachme
 this->ap.addPositional(p(&ArgParser::argCopyAttPositional));
 this->ap.addRequiredParameter("prefix", [this](std::string const& x){c_copy_att->prefix(x);}, "prefix");
 this->ap.addRequiredParameter("password", [this](std::string const& x){c_copy_att->password(x);}, "password");
+this->ap.registerOptionTable("set page labels", b(&ArgParser::argEndSetPageLabels));
+this->ap.addPositional(p(&ArgParser::argPageLabelsPositional));

libqpdf/qpdf/auto_job_json_decl.hh

@@ -44,6 +44,9 @@ void endPages();
 void setupPagesFile();
 void setupPagesPassword();
 void setupPagesRange();
+void beginSetPageLabelsArray(JSON);
+void endSetPageLabelsArray();
+void setupSetPageLabels();
 void beginOverlay(JSON);
 void endOverlay();
 void setupOverlayFile();

libqpdf/qpdf/auto_job_json_init.hh

@@ -421,6 +421,11 @@ popHandler(); // key: reportMemoryUsage
 pushKey("rotate");
 addParameter([this](std::string const& p) { c_main->rotate(p); });
 popHandler(); // key: rotate
+pushKey("setPageLabels");
+beginArray(bindJSON(&Handlers::beginSetPageLabelsArray), bindBare(&Handlers::endSetPageLabelsArray)); // .setPageLabels[]
+setupSetPageLabels();
+popHandler(); // array: .setPageLabels[]
+popHandler(); // key: setPageLabels
 pushKey("overlay");
 beginDict(bindJSON(&Handlers::beginOverlay), bindBare(&Handlers::endOverlay)); // .overlay
 pushKey("file");

libqpdf/qpdf/auto_job_schema.hh

@@ -148,6 +148,9 @@ static constexpr char const* JOB_SCHEMA_DATA = R"({
   "removePageLabels": "remove explicit page numbers",
   "reportMemoryUsage": "best effort report of memory usage",
   "rotate": "rotate pages",
+  "setPageLabels": [
+    "number pages for the entire document"
+  ],
   "overlay": {
     "file": "source file for overlay",
     "password": "password for encrypted file",

manual/qpdf.1

@@ -516,6 +516,45 @@ Prevent inline images from being considered by --optimize-images.
 .TP
 .B --remove-page-labels \-\- remove explicit page numbers
 Exclude page labels (explicit page numbers) from the output file.
+.TP
+.B --set-page-labels \-\- number pages for the entire document
+--set-page-labels label-spec ... --
+
+Set page labels (explicit page numbers) for the entire file.
+Each label-spec has the form
+
+first-page:[type][/start[/prefix]]
+
+where
+
+.IP \[bu]
+"first-page" represents a sequential page number using the
+same format as page ranges: a number, a number preceded by "r"
+to indicate counting from the end, or "z" indicating the last
+page
+.IP \[bu]
+"type" is one of
+- D: Arabic numerals (digits)
+- A: Upper-case alphabetic characters
+- a: Lower-case alphabetic characters
+- R: Upper-case Roman numerals
+- r: Lower-case Roman numerals
+- omitted: the page number does not appear, though the prefix,
+  if specified will still appear
+.IP \[bu]
+"prefix"` may be any string and is prepended to each page
+label
+
+A given page label spec causes pages to be numbered according to
+that scheme starting with first-page and continuing until the
+next label spec or the end of the document. If you want to omit
+numbering starting at a certain page, you can use first-page: as
+the spec.
+
+Example: "1:r 5:D" would number the first four pages i through
+iv, then the remaining pages with Arabic numerals starting with
+1 and continuing sequentially until the end of the document. For
+additional examples, please consult the manual.
 .SH ENCRYPTION (create encrypted files)
 Create encrypted files. Usage: