diff options
author | Jay Berkenbilt <ejb@ql.org> | 2019-01-27 00:45:34 +0100 |
---|---|---|
committer | Jay Berkenbilt <ejb@ql.org> | 2019-01-27 15:30:13 +0100 |
commit | 426434c77284597505ef0bc708a0694d4c622332 (patch) | |
tree | 140dbea718f8dd7afa3527a79b7efbabd3f9a212 /manual | |
parent | c2ae35540e78d4edfbc57d42bfa2fc166c38b8a5 (diff) | |
download | qpdf-426434c77284597505ef0bc708a0694d4c622332.tar.zst |
Add --overlay and --underlay to qpdf CLI (fixes #207)
Diffstat (limited to 'manual')
-rw-r--r-- | manual/qpdf-manual.xml | 165 |
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 “from” 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> |