From 426434c77284597505ef0bc708a0694d4c622332 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Sat, 26 Jan 2019 18:45:34 -0500 Subject: Add --overlay and --underlay to qpdf CLI (fixes #207) --- manual/qpdf-manual.xml | 165 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) (limited to 'manual/qpdf-manual.xml') 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 + + + + + Overlay pages from another file onto the output pages. See + for details on + overlay/underlay. + + + + + + + + Overlay pages from another file onto the output pages. See + for details on + overlay/underlay. + + + @@ -1234,6 +1254,94 @@ outfile.pdf Version 8.4 removes this limitation. + + Overlay and Underlay Options + + 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: + + { | } file [ ] + + Overlay and underlay options are processed late, so they can be + combined with other like merging and will apply to the final + output. The and + 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. + + + 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 + or flag and + the option. The following options are + supported: + + + + : supply a password if the + overlay/underlay file is encrypted. + + + + + : a range of pages in the same + form at described in + indicates which pages in the output should have the + overlay/underlay applied. If not specified, overlay/underlay + are applied to all pages. + + + + + : 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 + is used. + + + + + : 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 . + + + + + + Here are some examples. + + + + --overlay o.pdf --to=1-5 --from=1-3 + --repeat=4 --: overlay the first three pages from file + o.pdf onto the first three pages of the + output, then overlay page 4 from o.pdf + onto pages 4 and 5 of the output. Leave remaining output pages + untouched. + + + + + --underlay footer.pdf --from= --repeat=1,2 --: + Underlay page 1 of footer.pdf on all odd + output pages, and underlay page 2 of + footer.pdf on all even output pages. + + + + + Advanced Parsing Options @@ -4222,6 +4330,14 @@ print "\n"; + + + Add options and + for overlaying or underlaying + pages of other files onto output pages. See for details. + + When opening an encrypted file with a password, if the @@ -4372,6 +4488,55 @@ print "\n"; QPDF.hh for details. + + + Add method + QPDFPageObjectHelper::getAttribute 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. + + + + + Fix long-standing limitation of + QPDFPageObjectHelper::getPageImages so + that it now properly reports images from inherited resources + dictionaries, eliminating the need to call + QPDFPageDocumentHelper::pushInheritedAttributesToPage + in this case. + + + + + Add method + QPDFObjectHandle::getUniqueResourceName + for finding an unused name in a resource dictionary. + + + + + Add method + QPDFPageObjectHelper::getFormXObjectForPage + 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 copyForeignObject. + This can be useful for implementing underlay, overlay, n-up, + thumbnails, or any other functionality requiring replication + of pages in other contexts. + + + + + Add method + QPDFPageObjectHelper::placeFormXObject + 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. + + -- cgit v1.2.3-70-g09d2