Add --overlay and --underlay to qpdf CLI (fixes #207)

1 files changed, 165 insertions, 0 deletions

diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml
index 0b2ec813..169eba50 100644
--- a/manual/qpdf-manual.xml
+++ b/manual/qpdf-manual.xml
@@ -757,6 +757,26 @@ make
        </para>
       </listitem>
      </varlistentry>
+     <varlistentry>
+      <term><option>--overlay options --</option></term>
+      <listitem>
+       <para>
+        Overlay pages from another file onto the output pages. See
+        <xref linkend="ref.overlay-underlay"/> for details on
+        overlay/underlay.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><option>--underlay options --</option></term>
+      <listitem>
+       <para>
+        Overlay pages from another file onto the output pages. See
+        <xref linkend="ref.overlay-underlay"/> for details on
+        overlay/underlay.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
    <para>
@@ -1234,6 +1254,94 @@ outfile.pdf</option>
     Version 8.4 removes this limitation.
    </para>
   </sect1>
+  <sect1 id="ref.overlay-underlay">
+   <title>Overlay and Underlay Options</title>
+   <para>
+    Starting with qpdf 8.4, it is possible to overlay or underlay
+    pages from other files onto the output generated by qpdf. Specify
+    overlay or underlay as follows:
+
+    <programlisting>{ <option>--overlay</option> | <option>--underlay</option> } <replaceable>file</replaceable> [ <option>options</option> ] <option>--</option>
+</programlisting>
+    Overlay and underlay options are processed late, so they can be
+    combined with other like merging and will apply to the final
+    output. The <option>--overlay</option> and
+    <option>--underlay</option> options work the same way, except
+    underlay pages are drawn underneath the page to which they are
+    applied, possibly obscured by the origial 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.
+   </para>
+   <para>
+    The default behavior of overlay and underlay is that pages are
+    taken from the overlay/underlay file in sequence and applied to
+    corresponding pages in the output until there are no more output
+    pages. If the overlay or underlay file runs out of pages,
+    remaining output pages are left alone. This behavior can be
+    modified by options, which are provided between the
+    <option>--overlay</option> or <option>--underlay</option> flag and
+    the <option>--</option> option. The following options are
+    supported:
+    <itemizedlist>
+     <listitem>
+      <para>
+       <option>--password=password</option>: supply a password if the
+       overlay/underlay file is encrypted.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <option>--to=page-range</option>: a range of pages in the same
+       form at described in <xref linkend="ref.page-selection"/>
+       indicates which pages in the output should have the
+       overlay/underlay applied. If not specified, overlay/underlay
+       are applied to all pages.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <option>--from=[page-range]</option>: a range of pages that
+       specifies which pages in the overlay/underlay file will be used
+       for overlay or underlay. If not specified, all pages will be
+       used. This can be explicitly specified to be empty if
+       <option>--repeat</option> is used.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <option>--repeat=page-range</option>: an optional range of
+       pages that specifies which pages in the overlay/underlay file
+       will be repeated after the &ldquo;from&rdquo; pages are used
+       up. If you want to repeat a range of pages starting at the
+       beginning, you can explicitly use <option>--from=</option>.
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+   <para>
+    Here are some examples.
+    <itemizedlist>
+     <listitem>
+      <para>
+       <command>--overlay o.pdf --to=1-5 --from=1-3
+       --repeat=4 --</command>: overlay the first three pages from file
+       <filename>o.pdf</filename> onto the first three pages of the
+       output, then overlay page 4 from <filename>o.pdf</filename>
+       onto pages 4 and 5 of the output. Leave remaining output pages
+       untouched.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <command>--underlay footer.pdf --from= --repeat=1,2 --</command>:
+       Underlay page 1 of <filename>footer.pdf</filename> on all odd
+       output pages, and underlay page 2 of
+       <filename>footer.pdf</filename> on all even output pages.
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+  </sect1>
   <sect1 id="ref.advanced-parsing">
    <title>Advanced Parsing Options</title>
    <para>
@@ -4224,6 +4332,14 @@ print "\n";
         </listitem>
         <listitem>
          <para>
+          Add options <option>--overlay</option> and
+          <option>--underlay</option> for overlaying or underlaying
+          pages of other files onto output pages. See <xref
+          linkend="ref.overlay-underlay"/> for details.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
           When opening an encrypted file with a password, if the
           specified password doesn't work and the password contains
           any non-ASCII characters, qpdf will try a number of
@@ -4372,6 +4488,55 @@ print "\n";
           <filename>QPDF.hh</filename> for details.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          Add method
+          <function>QPDFPageObjectHelper::getAttribute</function> for
+          retrieving an attribute from the page dictionary taking
+          inheritence into consideration, and optionally making a copy
+          if your intention is to modify the attribute.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          Fix long-standing limitation of
+          <function>QPDFPageObjectHelper::getPageImages</function> so
+          that it now properly reports images from inherited resources
+          dictionaries, eliminating the need to call
+          <function>QPDFPageDocumentHelper::pushInheritedAttributesToPage</function>
+          in this case.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          Add method
+          <function>QPDFObjectHandle::getUniqueResourceName</function>
+          for finding an unused name in a resource dictionary.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          Add method
+          <function>QPDFPageObjectHelper::getFormXObjectForPage</function>
+          for generating a form XObject equivalent to a page. The
+          resulting object can be used in the same file or copied to
+          another file with <function>copyForeignObject</function>.
+          This can be useful for implementing underlay, overlay, n-up,
+          thumbnails, or any other functionality requiring replication
+          of pages in other contexts.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          Add method
+          <function>QPDFPageObjectHelper::placeFormXObject</function>
+          for generating content stream text that places a given form
+          XObject on a page, centered and fit within a specified
+          rectangle. This method takes care of computing the proper
+          transformation matrix and may optionally compensate for
+          rotation or scaling of the destination page.
+         </para>
+        </listitem>
        </itemizedlist>
       </listitem>
       <listitem>