mirror of
https://github.com/qpdf/qpdf.git
synced 2024-06-04 03:10:52 +00:00
Clarify documentation of advanced parsing options
This commit is contained in:
parent
794b649e5b
commit
48864b8d6e
|
@ -1,5 +1,12 @@
|
||||||
2017-12-25 Jay Berkenbilt <ejb@ql.org>
|
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
|
* Implement remaining PNG filters for decode. Prior versions could
|
||||||
decode only the "up" filter. Now all PNG filters (sub, up,
|
decode only the "up" filter. Now all PNG filters (sub, up,
|
||||||
average, Paeth, optimal) are supported for decoding. Thanks to
|
average, Paeth, optimal) are supported for decoding. Thanks to
|
||||||
|
|
|
@ -865,6 +865,56 @@ outfile.pdf</option>
|
||||||
to be bothered with.
|
to be bothered with.
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</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">
|
<sect1 id="ref.advanced-transformation">
|
||||||
<title>Advanced Transformation Options</title>
|
<title>Advanced Transformation Options</title>
|
||||||
<para>
|
<para>
|
||||||
|
@ -975,14 +1025,6 @@ outfile.pdf</option>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
|
||||||
<term><option>--suppress-recovery</option></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Prevents qpdf from attempting to recover damaged files.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><option>--object-streams=<replaceable>mode</replaceable></option></term>
|
<term><option>--object-streams=<replaceable>mode</replaceable></option></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
|
@ -1012,14 +1054,6 @@ outfile.pdf</option>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
|
||||||
<term><option>--ignore-xref-streams</option></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Tells qpdf to ignore any cross-reference streams.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><option>--preserve-unreferenced</option></term>
|
<term><option>--preserve-unreferenced</option></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
|
@ -1142,17 +1176,6 @@ outfile.pdf</option>
|
||||||
who wish to study PDF content streams or to debug PDF content.
|
who wish to study PDF content streams or to debug PDF content.
|
||||||
You should not use this for “production” PDF files.
|
You should not use this for “production” PDF files.
|
||||||
</para>
|
</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>
|
<para>
|
||||||
Object streams, also known as compressed objects, were introduced
|
Object streams, also known as compressed objects, were introduced
|
||||||
into the PDF specification at version 1.5, corresponding to
|
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
|
qpdf will also make sure the PDF version number in the header is
|
||||||
at least 1.5.
|
at least 1.5.
|
||||||
</para>
|
</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>
|
<para>
|
||||||
The <option>--qdf</option> flag turns on QDF mode, which changes
|
The <option>--qdf</option> flag turns on QDF mode, which changes
|
||||||
some of the defaults described above. Specifically, in QDF mode,
|
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\
|
See the manual for examples and a discussion of additional subtleties.\n\
|
||||||
\n\
|
\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\
|
Advanced Transformation Options\n\
|
||||||
-------------------------------\n\
|
-------------------------------\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\
|
--compress-streams=[yn] controls whether to compress streams on output\n\
|
||||||
--decode-level=option controls how to filter streams from the input\n\
|
--decode-level=option controls how to filter streams from the input\n\
|
||||||
--normalize-content=[yn] enables or disables normalization of content streams\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\
|
--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\
|
--preserve-unreferenced preserve unreferenced objects\n\
|
||||||
--newline-before-endstream always put a newline before endstream\n\
|
--newline-before-endstream always put a newline before endstream\n\
|
||||||
--qdf turns on \"QDF mode\" (below)\n\
|
--qdf turns on \"QDF mode\" (below)\n\
|
||||||
|
|
Loading…
Reference in New Issue
Block a user