From d8d70ecca264fa5c681dca992a03cfa4c46b3f43 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Mon, 1 Jan 2024 18:55:45 -0500 Subject: Support comma-separated numeric values with --collate (fixes #505) --- manual/cli.rst | 49 ++++++++++++++++++++++++++++++++++++++++++------ manual/qpdf.1 | 8 ++++++-- manual/release-notes.rst | 4 ++++ 3 files changed, 53 insertions(+), 8 deletions(-) (limited to 'manual') diff --git a/manual/cli.rst b/manual/cli.rst index 592ba6ef..4927205a 100644 --- a/manual/cli.rst +++ b/manual/cli.rst @@ -1403,18 +1403,21 @@ Related Options See also :qpdf:ref:`--split-pages`, :qpdf:ref:`--collate`, :ref:`page-ranges`. -.. qpdf:option:: --collate[=n] +.. qpdf:option:: --collate[=n[,m,...]] .. help: collate with --pages Collate rather than concatenate pages specified with --pages. With a numeric parameter, collate in groups of n. The default - is 1. Run qpdf --help=page-selection for additional details. + is 1. With comma-separated numeric parameters, take n from the + first file, m from the second, etc. Run + qpdf --help=page-selection for additional details. This option causes :command:`qpdf` to collate rather than concatenate pages specified with :qpdf:ref:`--pages`. With a numeric parameter, collate in groups of :samp:`{n}`. The default - is 1. + is 1. With comma-separated numeric parameters, take :samp:`{n}` + from the first file, :samp:`{m}` from the second, etc. Please see :ref:`page-selection` for additional details. @@ -2335,6 +2338,8 @@ Page Selection Use --collate=n to cause pages to be collated in groups of n pages (default 1) instead of concatenating the input. + Use --collate=i,j,k,... to take i from the first, then j from the + second, then k from the third, then i from the first, etc. Examples: @@ -2383,9 +2388,13 @@ Notes: See :ref:`page-ranges` for help on specifying a page range. Use :samp:`--collate={n}` to cause pages to be collated in groups of -:samp:`{n}` pages (default 1) instead of concatenating the input. Note -that the :qpdf:ref:`--collate` appears outside of ``--pages ... --`` -(before ``--pages`` or after ``--``). Pages are pulled from each +:samp:`{n}` pages (default 1) instead of concatenating the input. Use +:samp:`--collate={i},{j},{k},...` to take :samp:`{i}` from the first, +then :samp:`{j}` from the second, then :samp:`{k}` from the third, +then :samp:`{i}` from the first, etc. + +Note that the :qpdf:ref:`--collate` appears outside of ``--pages ... +--`` (before ``--pages`` or after ``--``). Pages are pulled from each document in turn. When a document is out of pages, it is skipped. See examples below. @@ -2481,6 +2490,34 @@ Examples - a.pdf page 5 +- You can specify a multiple numeric parameters to :qpdf:ref:`--collate`. With + :samp:`--collate={i,j,k}`, pull groups of :samp:`{i}` pages from the + first file, then :samp:`{j}` from the second, thenm :samp:`{k}` from + the third, repeating. The number of parameters must equal the number + of groups. For example, if you ran + + :: + + qpdf --collate=2,1,3 --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1-r4 -- out.pdf + + you would get the following pages in this order: + + - a.pdf pages 1 and 2 + + - b.pdf page 6 + + - c.pdf last three pages in reverse order + + - a.pdf pages 3 and 4 + + - b.pdf page 5 + + - c.pdf fourth to last page + + - a.pdf page 5 + + - b.pdf page 4 + - Take pages 1 through 5 from :file:`file1.pdf` and pages 11 through 15 in reverse from :file:`file2.pdf`, taking document-level metadata from :file:`file2.pdf`. diff --git a/manual/qpdf.1 b/manual/qpdf.1 index d758dca3..bf5e9792 100644 --- a/manual/qpdf.1 +++ b/manual/qpdf.1 @@ -414,11 +414,13 @@ Related Options: Run qpdf --help=page-selection for details. .TP .B --collate \-\- collate with --pages ---collate[=n] +--collate[=n[,m,...]] Collate rather than concatenate pages specified with --pages. With a numeric parameter, collate in groups of n. The default -is 1. Run qpdf --help=page-selection for additional details. +is 1. With comma-separated numeric parameters, take n from the +first file, m from the second, etc. Run +qpdf --help=page-selection for additional details. .TP .B --split-pages \-\- write pages to separate files --split-pages[=n] @@ -737,6 +739,8 @@ Run qpdf --help=page-ranges for help with page ranges. Use --collate=n to cause pages to be collated in groups of n pages (default 1) instead of concatenating the input. +Use --collate=i,j,k,... to take i from the first, then j from the +second, then k from the third, then i from the first, etc. Examples: diff --git a/manual/release-notes.rst b/manual/release-notes.rst index 17dc116d..72b1aad6 100644 --- a/manual/release-notes.rst +++ b/manual/release-notes.rst @@ -50,6 +50,10 @@ Planned changes for future 12.x (subject to change): of pages within a page range. See :ref:`page-ranges` for details. + - Support comma-separated numeric values with + :qpdf:ref:`--collate` to select different numbers of pages from + different groups. + 11.7.0: December 24, 2023 - Bug fixes: -- cgit v1.2.3-54-g00ecf