From ee437705fc87073d0223a005c6c5afd3fa464a7f Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Fri, 4 Jan 2019 21:54:59 -0500 Subject: Update documentation for new features --- manual/qpdf-manual.xml | 201 +++++++++++++++++++++++++++++++++++++++++++++++++ qpdf/qpdf.cc | 12 ++- 2 files changed, 209 insertions(+), 4 deletions(-) diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml index 8a44e928..d9eab50c 100644 --- a/manual/qpdf-manual.xml +++ b/manual/qpdf-manual.xml @@ -547,6 +547,16 @@ make + + + + + When specified, collate rather than concatenate pages from + files specified with . See for additional details. + + + @@ -965,6 +975,37 @@ make + + Starting in qpdf version 8.3, you can specify the + option. Note that this option is + specified outside of . + When is specified, it changes the + meaning of so that the specified files, + as modified by page ranges, are collated rather than concatenated. + For example, if you add the files odd.pdf and + even.pdf containing odd and even pages of a + document respectively, you could run qpdf --collate + odd.pdf --pages odd.pdf even.pdf -- all.pdf to collate + the pages. This would pick page 1 from odd, page 1 from even, page + 2 from odd, page 2 from even, etc. until all pages have been + included. Any number of files and page ranges can be specified. If + any file has fewer pages, that file is just skipped when its pages + have all been included. For example, if you ran qpdf + --collate --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1 -- + out.pdf, you would get the following pages in this + order: + + a.pdf page 1 + b.pdf page 6 + c.pdf last page + a.pdf page 2 + b.pdf page 5 + a.pdf page 3 + b.pdf page 4 + a.pdf page 4 + a.pdf page 5 + + 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 @@ -1301,6 +1342,166 @@ outfile.pdf + + + + + This option collapses annotations into the pages' contents + with special handling for form fields. Ordinarily, an + annotation is rendered separately and on top of the page. + Combining annotations into the page's contents effectively + freezes the placement of the annotations, making them look + right after various page transformations. The library + functionality backing this option was added for the benefit of + programs that want to create n-up page + layouts and other similar things that don't work well with + annotations. The option parameter + may be any of the following: + + + + : include all annotations that are not + marked invisible or hidden + + + + + : only include annotations that + indicate that they should appear when the page is printed + + + + + : omit annotations that indicate + they should not appear on the screen + + + + + + Note that form fields are special because the annotations that + are used to render filled-in form fields may become out of + date from the fields' values if the form is filled in by a + program that doesn't know how to update the appearances. If + qpdf detects this case, its default behavior is not to flatten + those annotations because doing so would cause the value of + the form field to be lost. This gives you a chance to go back + and resave the form with a program that knows how to generate + appearances. QPDF itself can generate appearances with some + limitations. See the + option below. + + + + + + + + If a file contains interactive form fields and indicates that + the appearances are out of date with the values of the form, + this flag will regenerate appearances, subject to a few + limitations. Note that there is not usually a reason to do + this, but it can be necessary before using the + option. Most of these + are not a problem with well-behaved PDF files. The limitations + are as follows: + + + + Radio button and checkbox appearances use the pre-set + values in the PDF file. QPDF just makes sure that the + correct appearance is displayed based on the value of the + field. This is fine for PDF files that create their forms + properly. Some PDF writers save appearances for fields when + they change, which could cause some controls to have + inconsistent appearances. + + + + + + + For text fields and list boxes, any characters that fall + outside of US-ASCII will be replaced by the + ? character. + + + + + + + Quadding is ignored. Quadding is used to specify whether + the contents of a field should be left, center, or right + aligned with the field. + + + + + + + Rich text, multi-line, and other more elaborate formatting + directives are ignored. + + + + + + + There is no support for multi-select fields or signature + fields. + + + + If qpdf doesn't do a good enough job with your form, use an + external application to save your filled-in form before + processing it with qpdf. + + + + + + + + This flag causes qpdf to recompress all images that are not + compressed with DCT (JPEG) using DCT compression as long as + doing so decreases the size in bytes of the image data and the + image does not fall below minimum specified dimensions. See + also the , + , and + options. + + + + + + + + Avoid optimizing images whose width is below the specified + amount. If omitted, the default is 128 pixels. Use 0 for no + minimum. + + + + + + + + Avoid optimizing images whose height is below the specified + amount. If omitted, the default is 128 pixels. Use 0 for no + minimum. + + + + + + + + Avoid optimizing images whose pixel count + (width × height) is below the specified amount. If + omitted, the default is 16,384 pixels. Use 0 for no minimum. + + + diff --git a/qpdf/qpdf.cc b/qpdf/qpdf.cc index bde83bfd..1f8aea50 100644 --- a/qpdf/qpdf.cc +++ b/qpdf/qpdf.cc @@ -130,9 +130,9 @@ struct Options json(false), check(false), optimize_images(false), - oi_min_width(128), - oi_min_height(128), - oi_min_area(16384), + oi_min_width(128), // Default values for these + oi_min_height(128), // oi flags are in --help + oi_min_area(16384), // and in the manual. require_outfile(true), infilename(0), outfilename(0) @@ -1162,9 +1162,12 @@ ArgParser::argHelp() << " fields; may also want --generate-appearances\n" << "--generate-appearances generate appearance streams for form fields\n" << "--optimize-images compress images with DCT (JPEG) when advantageous\n" - << "--oi-min-width=w do not optimize images whose width is below w\n" + << "--oi-min-width=w do not optimize images whose width is below w;\n" + << " default is 128. Use 0 to mean no minimum\n" << "--oi-min-height=h do not optimize images whose height is below h\n" + << " default is 128. Use 0 to mean no minimum\n" << "--oi-min-area=a do not optimize images whose pixel count is below a\n" + << " default is 16,384. Use 0 to mean no minimum\n" << "--qdf turns on \"QDF mode\" (below)\n" << "--linearize-pass1=file write intermediate pass of linearized file\n" << " for debugging\n" @@ -3609,6 +3612,7 @@ static void handle_transformations(QPDF& pdf, Options& o) QPDFPageDocumentHelper dh(pdf); if (o.optimize_images) { + dh.pushInheritedAttributesToPage(); int pageno = 0; std::vector pages = dh.getAllPages(); for (std::vector::iterator iter = pages.begin(); -- cgit v1.2.3-54-g00ecf