Support excluding values from numeric ranges (fixes #564, #790)

3 files changed, 47 insertions, 10 deletions

diff --git a/manual/cli.rst b/manual/cli.rst
index 457796e3..592ba6ef 100644
--- a/manual/cli.rst
+++ b/manual/cli.rst
@@ -1274,12 +1274,19 @@ Page Ranges
 .. help-topic page-ranges: page range syntax
 
    A full description of the page range syntax, with examples, can be
-   found in the manual. Summary:
+   found in the manual. In summary, a range is a comma-separated list
+   of groups. A group is a number or a range of numbers separated by a
+   dash. A group may be prepended by x to exclude its members from the
+   previous group. A number may be one of
 
-   - a,b,c    pages a, b, and c
-   - a-b      pages a through b inclusive; if a > b, this counts down
-   - r<n>     where <n> represents a number is the <n>th page from the end
-   - z        the last page, same as r1
+   - <n>        where <n> represents a number is the <n>th page
+   - r<n>       is the <n>th page from the end
+   - z          the last page, same as r1
+
+   - a,b,c      pages a, b, and c
+   - a-b        pages a through b inclusive; if a > b, this counts down
+   - a-b,xc     pages a through b except page c
+   - a-b,xc-d   pages a through b except pages c through d
 
    You can append :even or :odd to select every other page from the
    resulting set of pages, where :odd starts with the first page and
@@ -1303,6 +1310,10 @@ section describes the syntax of a page range.
   of pages from the first to the second. If the first number is higher
   than the second number, it is the range of pages in reverse.
 
+- A number or dash-separated range of numbers may be prepended with
+  ``x`` (from qpdf 11.7.1). This means to exclude the pages in that
+  range from the previous range that didn't start with ``x``.
+
 - The range may be appended with ``:odd`` or ``:even`` to select only
   pages from the resulting range in odd or even positions. In this
   case, odd and even refer to positions in the final range, not
@@ -1350,6 +1361,16 @@ section describes the syntax of a page range.
      - pages 7 and 9, which are the pages in even positions from the
        original set of 5, 7, 8, 9, 12
 
+   - - ``1-10,x3-4``
+     - pages 1 through 10 except pages 3 and 4 (1, 2, and 5
+       through 10)
+
+   - - ``4-10,x7-9,12-8,xr5``
+     - In a 15-page file, this is 4, 5, 6, 10, 12, 10, 9, and 8 in
+       that order. That is pages 4 through 10 except 7 through 9
+       followed by 12 through 8 descending except 11 (the fifth page
+       from the end)
+
 .. _modification-options:
 
 PDF Modification
diff --git a/manual/qpdf.1 b/manual/qpdf.1
index 6a859c8a..d758dca3 100644
--- a/manual/qpdf.1
+++ b/manual/qpdf.1
@@ -377,16 +377,26 @@ value, even if the file uses features that may not be available
 in that version.
 .SH PAGE-RANGES (page range syntax)
 A full description of the page range syntax, with examples, can be
-found in the manual. Summary:
+found in the manual. In summary, a range is a comma-separated list
+of groups. A group is a number or a range of numbers separated by a
+dash. A group may be prepended by x to exclude its members from the
+previous group. A number may be one of
 
 .IP \[bu]
-a,b,c    pages a, b, and c
+<n>        where <n> represents a number is the <n>th page
 .IP \[bu]
-a-b      pages a through b inclusive; if a > b, this counts down
+r<n>       is the <n>th page from the end
 .IP \[bu]
-r<n>     where <n> represents a number is the <n>th page from the end
+z          the last page, same as r1
+
+.IP \[bu]
+a,b,c      pages a, b, and c
+.IP \[bu]
+a-b        pages a through b inclusive; if a > b, this counts down
+.IP \[bu]
+a-b,xc     pages a through b except page c
 .IP \[bu]
-z        the last page, same as r1
+a-b,xc-d   pages a through b except pages c through d
 
 You can append :even or :odd to select every other page from the
 resulting set of pages, where :odd starts with the first page and
diff --git a/manual/release-notes.rst b/manual/release-notes.rst
index 9a8ea027..17dc116d 100644
--- a/manual/release-notes.rst
+++ b/manual/release-notes.rst
@@ -44,6 +44,12 @@ Planned changes for future 12.x (subject to change):
     - When flattening annotations, preserve hyperlinks and other
       annotations that inherently have no appearance information.
 
+  - CLI Enhancements
+
+    - Introduce ``x`` in the numeric range syntax to allow exclusion
+      of pages within a page range. See :ref:`page-ranges` for
+      details.
+
 11.7.0: December 24, 2023
   - Bug fixes: