Wiring for --set-page-labels: manual (non-bisectable commit)

This commit contains only the manual changes. It is separated for
clarity. This commit would not pass CI because it lacks the automated
changes, which appear in the next commit.

1 files changed, 110 insertions, 0 deletions

diff --git a/manual/cli.rst b/manual/cli.rst
index 1d530641..6495829f 100644
--- a/manual/cli.rst
+++ b/manual/cli.rst
@@ -1748,6 +1748,116 @@ Related Options
       Exclude page labels (explicit page numbers) from the output file.
 
    Exclude page labels (explicit page numbers) from the output file.
+   See also :qpdf:ref:`--set-page-labels`.
+
+.. qpdf:option:: --set-page-labels label-spec ... --
+
+   .. help: number pages for the entire document
+
+      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.
+
+   Set page labels (explicit page numbers) for the entire file. 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,
+   which defaults to 1. A qpdf page label spec has the form
+
+   :samp:`{first-page}:[{type}][/{start}[/{prefix}]]`
+
+   where
+
+   - :samp:`{first-page}` represents a sequential page number using
+     the same format as page ranges (see :ref:`page-ranges`): a
+     number, a number preceded by ``r`` to indicate counting from the
+     end, or ``z`` indicating the last page
+
+   - :samp:`{type}` may be 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
+
+   - :samp:`{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 :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,
+   assume a 50-page document.
+
+   - ``1:a 5:D``
+
+     - The first four pages will be numbered ``a`` through ``d``, then
+       the remaining pages will numbered ``1`` through ``46``.
+
+   - ``1:r 5:D 12: 14:D/10 r5:D//A- z://"end note"``:
+
+     - The first four pages are numbered ``i`` through ``iv``
+
+     - The 5th page is numbered ``1``, and pages are numbered
+       sequentially through the 11th page, which will be numbered
+       ``7``
+
+     - The 12th and 13th pages will not have labels
+
+     - The 14th page is numbered ``10``. Pages will be numered
+       sequentially up through the 45th page, which will be numbered
+       ``41``
+
+     - Starting with the 46th page (the fifth to last page) and going
+       to the 49th page, pages will be labeled ``A-1`` through ``A-4``
+
+     - The 50th page (the last page) will be labeled ``end note``.
+
+   The limitations on the range of formats for page labels are as
+   specified in Section 12.4.2 of the PDF spec, ISO 32000.
+
+   See also :qpdf:ref:`--remove-page-labels`.
 
 .. _encryption-options: