octoleo/qpdf
2
1
Fork 0
mirror of https://github.com/qpdf/qpdf.git synced 2024-06-05 03:40:53 +00:00
Code Issues Releases Wiki Activity

Update documentation for new features

Browse Source
This commit is contained in:
Jay Berkenbilt 2019-01-04 21:54:59 -05:00
parent ab9f4cc212
commit ee437705fc
2 changed files with 209 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

201
manual/qpdf-manual.xml
View File

@ -547,6 +547,16 @@ make
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--collate</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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--split-pages=[n]</option></term>
<listitem>
@ -965,6 +975,37 @@ make
</listitem>
</itemizedlist>
</para>
<para>
Starting in qpdf version 8.3, you can specify the
<option>--collate</option> option. Note that this option is
specified outside of <option>--pages&nbsp;...&nbsp;--</option>.
When <option>--collate</option> is specified, it changes the
meaning of <option>--pages</option> so that the specified files,
as modified by page ranges, are collated rather than concatenated.
For example, if you add the files <filename>odd.pdf</filename> and
<filename>even.pdf</filename> containing odd and even pages of a
document respectively, you could run <command>qpdf --collate
odd.pdf --pages odd.pdf even.pdf -- all.pdf</command> 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 <command>qpdf
--collate --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>b.pdf page 6</para></listitem>
<listitem><para>c.pdf last page</para></listitem>
<listitem><para>a.pdf page 2</para></listitem>
<listitem><para>b.pdf page 5</para></listitem>
<listitem><para>a.pdf page 3</para></listitem>
<listitem><para>b.pdf page 4</para></listitem>
<listitem><para>a.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
@ -1301,6 +1342,166 @@ outfile.pdf</option>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--flatten-annotations=<replaceable>option</replaceable></option></term>
<listitem>
<para>
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 <emphasis>n-up</emphasis> page
layouts and other similar things that don't work well with
annotations. The <replaceable>option</replaceable> parameter
may be any of the following:
<itemizedlist>
<listitem>
<para>
<option>all</option>: include all annotations that are not
marked invisible or hidden
</para>
</listitem>
<listitem>
<para>
<option>print</option>: only include annotations that
indicate that they should appear when the page is printed
</para>
</listitem>
<listitem>
<para>
<option>screen</option>: omit annotations that indicate
they should not appear on the screen
</para>
</listitem>
</itemizedlist>
</para>
<para>
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>--generate-appearances</option>
option below.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-appearances</option></term>
<listitem>
<para>
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>--flatten-annotations</option> option. Most of these
are not a problem with well-behaved PDF files. The limitations
are as follows:
<itemizedlist>
<listitem>
<para>
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.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
For text fields and list boxes, any characters that fall
outside of US-ASCII will be replaced by the
<literal>?</literal> character.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
Quadding is ignored. Quadding is used to specify whether
the contents of a field should be left, center, or right
aligned with the field.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
Rich text, multi-line, and other more elaborate formatting
directives are ignored.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
There is no support for multi-select fields or signature
fields.
</para>
</listitem>
</itemizedlist>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--optimize-images</option></term>
<listitem>
<para>
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 <option>--oi-min-width</option>,
<option>--oi-min-height</option>, and
<option>--oi-min-area</option> options.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--oi-min-width=<replaceable>width</replaceable></option></term>
<listitem>
<para>
Avoid optimizing images whose width is below the specified
amount. If omitted, the default is 128 pixels. Use 0 for no
minimum.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--oi-min-height=<replaceable>height</replaceable></option></term>
<listitem>
<para>
Avoid optimizing images whose height is below the specified
amount. If omitted, the default is 128 pixels. Use 0 for no
minimum.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--oi-min-area=<replaceable>area-in-pixels</replaceable></option></term>
<listitem>
<para>
Avoid optimizing images whose pixel count
(width&nbsp;×&nbsp;height) is below the specified amount. If
omitted, the default is 16,384 pixels. Use 0 for no minimum.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--qdf</option></term>
<listitem>

12
qpdf/qpdf.cc
View File

@ -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<QPDFPageObjectHelper> pages = dh.getAllPages();
for (std::vector<QPDFPageObjectHelper>::iterator iter = pages.begin();