mirror of
https://github.com/qpdf/qpdf.git
synced 2024-12-31 05:51:51 +00:00
Clarify documentation of advanced parsing options
This commit is contained in:
Jay Berkenbilt
parent
794b649e5b
commit
48864b8d6e
@ -1,5 +1,12 @@
|
||||
2017-12-25 Jay Berkenbilt <ejb@ql.org>
|
||||
|
||||
* Clarify documentation around options that control parsing but
|
||||
not output creation. Two options: --suppress-recovery and
|
||||
--ignore-xref-streams, were documented in the "Advanced
|
||||
Transformation Options" section of the manual and --help output
|
||||
even though they are not related to output. These are now
|
||||
described in a separate section called "Advanced Parsing Options."
|
||||
|
||||
* Implement remaining PNG filters for decode. Prior versions could
|
||||
decode only the "up" filter. Now all PNG filters (sub, up,
|
||||
average, Paeth, optimal) are supported for decoding. Thanks to
|
||||
|
||||
@ -865,6 +865,56 @@ outfile.pdf</option>
|
||||
to be bothered with.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="ref.advanced-parsing">
|
||||
<title>Advanced Parsing Options</title>
|
||||
<para>
|
||||
These options control aspects of how qpdf reads PDF files. Mostly
|
||||
these are of use to people who are working with damaged files.
|
||||
There is little reason to use these options unless you are trying
|
||||
to solve specific problems. The following options are available:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>--suppress-recovery</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Prevents qpdf from attempting to recover damaged files.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>--ignore-xref-streams</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Tells qpdf to ignore any cross-reference streams.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
Ordinarily, qpdf will attempt to recover from certain types of
|
||||
errors in PDF files. These include errors in the cross-reference
|
||||
table, certain types of object numbering errors, and certain types
|
||||
of stream length errors. Sometimes, qpdf may think it has
|
||||
recovered but may not have actually recovered, so care should be
|
||||
taken when using this option as some data loss is possible. The
|
||||
<option>--suppress-recovery</option> option will prevent qpdf from
|
||||
attempting recovery. In this case, it will fail on the first
|
||||
error that it encounters.
|
||||
</para>
|
||||
<para>
|
||||
Ordinarily, qpdf reads cross-reference streams when they are
|
||||
present in a PDF file. If <option>--ignore-xref-streams</option>
|
||||
is specified, qpdf will ignore any cross-reference streams for
|
||||
hybrid PDF files. The purpose of hybrid files is to make some
|
||||
content available to viewers that are not aware of cross-reference
|
||||
streams. It is almost never desirable to ignore them. The only
|
||||
time when you might want to use this feature is if you are testing
|
||||
creation of hybrid PDF files and wish to see how a PDF consumer
|
||||
that doesn't understand object and cross-reference streams would
|
||||
interpret such a file.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="ref.advanced-transformation">
|
||||
<title>Advanced Transformation Options</title>
|
||||
<para>
|
||||
@ -975,14 +1025,6 @@ outfile.pdf</option>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>--suppress-recovery</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Prevents qpdf from attempting to recover damaged files.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>--object-streams=<replaceable>mode</replaceable></option></term>
|
||||
<listitem>
|
||||
@ -1012,14 +1054,6 @@ outfile.pdf</option>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>--ignore-xref-streams</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Tells qpdf to ignore any cross-reference streams.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>--preserve-unreferenced</option></term>
|
||||
<listitem>
|
||||
@ -1142,17 +1176,6 @@ outfile.pdf</option>
|
||||
who wish to study PDF content streams or to debug PDF content.
|
||||
You should not use this for “production” PDF files.
|
||||
</para>
|
||||
<para>
|
||||
Ordinarily, qpdf will attempt to recover from certain types of
|
||||
errors in PDF files. These include errors in the cross-reference
|
||||
table, certain types of object numbering errors, and certain types
|
||||
of stream length errors. Sometimes, qpdf may think it has
|
||||
recovered but may not have actually recovered, so care should be
|
||||
taken when using this option as some data loss is possible. The
|
||||
<option>--suppress-recovery</option> option will prevent qpdf from
|
||||
attempting recovery. In this case, it will fail on the first
|
||||
error that it encounters.
|
||||
</para>
|
||||
<para>
|
||||
Object streams, also known as compressed objects, were introduced
|
||||
into the PDF specification at version 1.5, corresponding to
|
||||
@ -1177,18 +1200,6 @@ outfile.pdf</option>
|
||||
qpdf will also make sure the PDF version number in the header is
|
||||
at least 1.5.
|
||||
</para>
|
||||
<para>
|
||||
Ordinarily, qpdf reads cross-reference streams when they are
|
||||
present in a PDF file. If <option>--ignore-xref-streams</option>
|
||||
is specified, qpdf will ignore any cross-reference streams for
|
||||
hybrid PDF files. The purpose of hybrid files is to make some
|
||||
content available to viewers that are not aware of cross-reference
|
||||
streams. It is almost never desirable to ignore them. The only
|
||||
time when you might want to use this feature is if you are testing
|
||||
creation of hybrid PDF files and wish to see how a PDF consumer
|
||||
that doesn't understand object and cross-reference streams would
|
||||
interpret such a file.
|
||||
</para>
|
||||
<para>
|
||||
The <option>--qdf</option> flag turns on QDF mode, which changes
|
||||
some of the defaults described above. Specifically, in QDF mode,
|
||||
|
||||
13
qpdf/qpdf.cc
13
qpdf/qpdf.cc
@ -355,6 +355,17 @@ valid file name and not a valid range.\n\
|
||||
See the manual for examples and a discussion of additional subtleties.\n\
|
||||
\n\
|
||||
\n\
|
||||
Advanced Parsing Options\n\
|
||||
-------------------------------\n\
|
||||
\n\
|
||||
These options control aspects of how qpdf reads PDF files. Mostly these are\n\
|
||||
of use to people who are working with damaged files. There is little reason\n\
|
||||
to use these options unless you are trying to solve specific problems.\n\
|
||||
\n\
|
||||
--suppress-recovery prevents qpdf from attempting to recover damaged files\n\
|
||||
--ignore-xref-streams tells qpdf to ignore any cross-reference streams\n\
|
||||
\n\
|
||||
\n\
|
||||
Advanced Transformation Options\n\
|
||||
-------------------------------\n\
|
||||
\n\
|
||||
@ -366,9 +377,7 @@ familiar with the PDF file format or who are PDF developers.\n\
|
||||
--compress-streams=[yn] controls whether to compress streams on output\n\
|
||||
--decode-level=option controls how to filter streams from the input\n\
|
||||
--normalize-content=[yn] enables or disables normalization of content streams\n\
|
||||
--suppress-recovery prevents qpdf from attempting to recover damaged files\n\
|
||||
--object-streams=mode controls handing of object streams\n\
|
||||
--ignore-xref-streams tells qpdf to ignore any cross-reference streams\n\
|
||||
--preserve-unreferenced preserve unreferenced objects\n\
|
||||
--newline-before-endstream always put a newline before endstream\n\
|
||||
--qdf turns on \"QDF mode\" (below)\n\
|
||||
|
||||
Loading…
Reference in New Issue
Block a user