From 070ee710eb0aaf6ddc845735c6ea0c28d3b7e5a1 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Mon, 1 Jan 2024 10:14:01 -0500 Subject: Support excluding values from numeric ranges (fixes #564, #790) --- manual/cli.rst | 31 ++++++++++++++++++++++++++----- manual/qpdf.1 | 20 +++++++++++++++----- manual/release-notes.rst | 6 ++++++ 3 files changed, 47 insertions(+), 10 deletions(-) (limited to 'manual') 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 where represents a number is the th page from the end - - z the last page, same as r1 + - where represents a number is the th page + - r is the 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 + where represents a number is the th page .IP \[bu] -a-b pages a through b inclusive; if a > b, this counts down +r is the th page from the end .IP \[bu] -r where represents a number is the 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: -- cgit v1.2.3-54-g00ecf