Allow --file with --overlay and --underlay

3 files changed, 22 insertions, 5 deletions

diff --git a/manual/cli.rst b/manual/cli.rst
index 70253a5f..0ccdee8f 100644
--- a/manual/cli.rst
+++ b/manual/cli.rst
@@ -2789,7 +2789,7 @@ Overlay and Underlay
    the destination page and may obscure the page. Underlaid pages are
    drawn below the destination page. Usage:
 
-   {--overlay|--underlay} file
+   {--overlay|--underlay} [--file=]file
          [--password=password]
          [--to=page-range]
          [--from=[page-range]]
@@ -2813,7 +2813,7 @@ as follows:
 
 ::
 
-   {--overlay|--underlay} file [options] --
+   {--overlay|--underlay} [--file=]file [options] --
 
 Overlay and underlay options are processed late, so they can be
 combined with other options like merging and will apply to the final
@@ -2821,8 +2821,10 @@ 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, but you can
-only specify each option at most one time.
+obscuring the page. The ability to specify the file using the
+:qpdf:ref:`--file` option was added in qpdf 11.9.0. 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
diff --git a/manual/qpdf.1 b/manual/qpdf.1
index 4de6427d..edad42b3 100644
--- a/manual/qpdf.1
+++ b/manual/qpdf.1
@@ -833,7 +833,7 @@ underlaid on the primary output. Overlaid pages are drawn on top of
 the destination page and may obscure the page. Underlaid pages are
 drawn below the destination page. Usage:
 
-{--overlay|--underlay} file
+{--overlay|--underlay} [--file=]file
       [--password=password]
       [--to=page-range]
       [--from=[page-range]]
diff --git a/manual/release-notes.rst b/manual/release-notes.rst
index 53d41942..938d2705 100644
--- a/manual/release-notes.rst
+++ b/manual/release-notes.rst
@@ -38,6 +38,21 @@ Planned changes for future 12.x (subject to change):
 
 .. x.y.z: not yet released
 
+11.9.0: not yet released
+  - CLI Enhancements
+
+    - Add new command-line arguments :qpdf:ref:`--file` and
+      :qpdf:ref:`--range` which can be used within :qpdf:ref:`--pages`
+      in place of positional arguments. Allow :qpdf:ref:`--file` to be
+      used inside of :qpdf:ref:`--overlay` and :qpdf:ref:`--underlay`
+      as well. These new options can be freely intermixed with
+      positional arguments.
+
+  - Library Enhancements
+
+    - Add ``file()``, ``range()``, and ``password()`` to
+      ``QPDFJob::PagesConfig`` as an alternative to ``pageSpec``.
+
 11.8.0: January 8, 2024
   - Bug fixes: