From dfce581754142d37308313b6788598771f242039 Mon Sep 17 00:00:00 2001
From: Jay Berkenbilt <ejb@ql.org>
Date: Wed, 17 Feb 2021 20:04:55 -0500
Subject: Add numeric argument to --collate

This takes pages from the file in groups of n with default = 1. This
partially fixes the enhancement in issue #505 but doesn't implement
the entire suggestion.
---
 manual/qpdf-manual.xml | 37 ++++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

(limited to 'manual/qpdf-manual.xml')

diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml
index 508e0ec9..144c4edf 100644
--- a/manual/qpdf-manual.xml
+++ b/manual/qpdf-manual.xml
@@ -1077,12 +1077,14 @@ make
       </listitem>
      </varlistentry>
      <varlistentry>
-      <term><option>--collate</option></term>
+      <term><option>--collate=<replaceable>n</replaceable></option></term>
       <listitem>
        <para>
         When specified, collate rather than concatenate pages from
-        files specified with <option>--pages</option>.  See <xref
-        linkend="ref.page-selection"/> for additional details.
+        files specified with <option>--pages</option>. With a numeric
+        argument, collate in groups of <replaceable>n</replaceable>.
+        The default is 1. See <xref linkend="ref.page-selection"/> for
+        additional details.
        </para>
       </listitem>
      </varlistentry>
@@ -1646,6 +1648,27 @@ make
      <listitem><para>a.pdf page 5</para></listitem>
     </itemizedlist>
    </para>
+   <para>
+    Starting in qpdf version 10.2, you may specify a numeric argument
+    to <option>--collate</option>. With
+    <option>--collate=<replaceable>n</replaceable></option>, pull
+    groups of <replaceable>n</replaceable> pages from each file,
+    again, stopping when there are no more pages. For example, if you
+    ran <command>qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4
+    c.pdf r1 -- out.pdf</command>, you would get the following pages
+    in this order:
+    <itemizedlist>
+     <listitem><para>a.pdf page 1</para></listitem>
+     <listitem><para>a.pdf page 2</para></listitem>
+     <listitem><para>b.pdf page 6</para></listitem>
+     <listitem><para>b.pdf page 5</para></listitem>
+     <listitem><para>c.pdf last page</para></listitem>
+     <listitem><para>a.pdf page 3</para></listitem>
+     <listitem><para>a.pdf page 4</para></listitem>
+     <listitem><para>b.pdf page 4</para></listitem>
+     <listitem><para>a.pdf page 5</para></listitem>
+    </itemizedlist>
+   </para>
    <para>
     Starting in qpdf version 8.3, when you split and merge files, any
     page labels (page numbers) are preserved in the final file. It is
@@ -5144,6 +5167,14 @@ print "\n";
           reference to the file spec object.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          Add numeric option to <option>--collate</option>. If
+          <option>--collate=<replaceable>n</replaceable></option> is
+          given, take pages in groups of <replaceable>n</replaceable>
+          from the given files.
+         </para>
+        </listitem>
        </itemizedlist>
       </listitem>
       <listitem>
-- 
cgit v1.2.3-54-g00ecf