Documentation fixes for set/remove page labels

4 files changed, 43 insertions, 7 deletions

diff --git a/job.sums b/job.sums
index dddf5fa3..6f04d8d4 100644
--- a/job.sums
+++ b/job.sums
@@ -9,12 +9,12 @@ include/qpdf/auto_job_c_pages.hh 09ca15649cc94fdaf6d9bdae28a20723f2a66616bf15aa8
 include/qpdf/auto_job_c_uo.hh 9c2f98a355858dd54d0bba444b73177a59c9e56833e02fa6406f429c07f39e62
 job.yml 53cad86659db6722e8f415aacb19fc51ab81bb1589c3cb8f65ec893bb4bf5566
 libqpdf/qpdf/auto_job_decl.hh 20d6affe1e260f5a1af4f1d82a820b933835440ff03020e877382da2e8dac6c6
-libqpdf/qpdf/auto_job_help.hh e4bb9e097516f35b4dbc676e1de99f294d8f42912541c8e3844ea401e44336ef
+libqpdf/qpdf/auto_job_help.hh 74b2982771720927ce7be8f1690720ec65cb9989620493a0c154f50ba2c254e4
 libqpdf/qpdf/auto_job_init.hh 19d1da7c4c0c635bd1c5db8d5f17df8edad3442f8eba006adb075cec295fa158
 libqpdf/qpdf/auto_job_json_decl.hh 843892c8e8652a86b7eb573893ef24050b7f36fe313f7251874be5cd4cdbe3fd
 libqpdf/qpdf/auto_job_json_init.hh a87256c082427ec0318223762472970b2eced535c0c8b0288d45c8cdaaf62f74
 libqpdf/qpdf/auto_job_schema.hh 5dac568dff39614e161a0af59a0f328f1e28edf69b96f08bb76fd592d51bb053
 manual/_ext/qpdf.py 6add6321666031d55ed4aedf7c00e5662bba856dfcd66ccb526563bffefbb580
-manual/cli.rst 98219ac9942824b78119cca7cd75691f7c98a31ed3c8b4f108d60a699087c418
-manual/qpdf.1 2544e085c5f0f92e242944eea3bc5736e1036f67595a7a7c988f4ea8d75da901
+manual/cli.rst 313e73730b062b52897ebbd72605d73fda3c6eb5028f4818e0da2100c75af5bc
+manual/qpdf.1 63d6ca1f7c41cfec3f82bc17aa4f40218635ad32a5a171d02bca62e1ddae45dd
 manual/qpdf.1.in 436ecc85d45c4c9e2dbd1725fb7f0177fb627179469f114561adf3cb6cbb677b
diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh
index cd594e9c..79c32ceb 100644
--- a/libqpdf/qpdf/auto_job_help.hh
+++ b/libqpdf/qpdf/auto_job_help.hh
@@ -437,9 +437,18 @@ where
   - r: Lower-case Roman numerals
   - omitted: the page number does not appear, though the prefix,
     if specified will still appear
+- "start" must be a number >= 1
 - "prefix"` may be any string and is prepended to each page
   label
 
+The first label spec must have a first-page value of 1,
+indicating the first page of the document. If multiple page
+label specs are specified, they must be given in increasing
+order.
+
+If multiple page label specs are specified, they must be given
+in increasing order.
+
 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
diff --git a/manual/cli.rst b/manual/cli.rst
index dc82bf88..aee2c8ec 100644
--- a/manual/cli.rst
+++ b/manual/cli.rst
@@ -1779,7 +1779,8 @@ Related Options
 
       Exclude page labels (explicit page numbers) from the output file.
 
-   Exclude page labels (explicit page numbers) from the output file.
+   Exclude page labels (explicit page numbers) from the output file by
+   omitting the ``/PageLabels`` dictionary in the document catalog.
    See also :qpdf:ref:`--set-page-labels`.
 
 .. qpdf:option:: --set-page-labels label-spec ... --
@@ -1805,9 +1806,18 @@ Related Options
         - r: Lower-case Roman numerals
         - omitted: the page number does not appear, though the prefix,
           if specified will still appear
+      - "start" must be a number >= 1
       - "prefix"` may be any string and is prepended to each page
         label
 
+      The first label spec must have a first-page value of 1,
+      indicating the first page of the document. If multiple page
+      label specs are specified, they must be given in increasing
+      order.
+
+      If multiple page label specs are specified, they must be given
+      in increasing order.
+
       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
@@ -1819,8 +1829,9 @@ Related Options
       1 and continuing sequentially until the end of the document. For
       additional examples, please consult the manual.
 
-   Set page labels (explicit page numbers) for the entire file. A PDF
-   file's pages can be explicitly numbered using page labels. Page
+   Set page labels (explicit page numbers) for the entire file. This
+   generates a ``/PageLabels`` dictionary in the document catalog. A
+   PDF file's pages can be explicitly numbered using page labels. Page
    labels in a PDF file have an optional type (Arabic numerals,
    upper/lower-case alphabetic characters, upper/lower-case Roman
    numerals), an optional prefix, and an optional starting value,
@@ -1850,16 +1861,22 @@ Related Options
      - omitted: the page number does not appear, though the prefix, if
        specified will still appear
 
+   - :samp:`{start}` must be a number ≥ 1
+
    - :samp:`{prefix}` may be any string and is prepended to each page
      label
 
+   The first label spec must have a :samp:`{first-page}` value of
+   ``1``, indicating the first page of the document. If multiple page
+   label specs are specified, they must be given in increasing order.
+
    A given page label spec causes pages to be numbered according to
    that scheme starting with :samp:`{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
    :samp:`{first-page}:` as the spec.
 
-   Here are some example page labeling schemes. First these examples,
+   Here are some example page labeling schemes. For these examples,
    assume a 50-page document.
 
    - ``1:a 5:D``
diff --git a/manual/qpdf.1 b/manual/qpdf.1
index 8aa19d06..d0b2d05e 100644
--- a/manual/qpdf.1
+++ b/manual/qpdf.1
@@ -558,9 +558,19 @@ page
 - omitted: the page number does not appear, though the prefix,
   if specified will still appear
 .IP \[bu]
+"start" must be a number >= 1
+.IP \[bu]
 "prefix"` may be any string and is prepended to each page
 label
 
+The first label spec must have a first-page value of 1,
+indicating the first page of the document. If multiple page
+label specs are specified, they must be given in increasing
+order.
+
+If multiple page label specs are specified, they must be given
+in increasing order.
+
 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