diff options
| -rw-r--r-- | ChangeLog | 7 | ||||
| -rw-r--r-- | manual/qpdf-manual.xml | 89 | ||||
| -rw-r--r-- | qpdf/qpdf.cc | 13 |
3 files changed, 68 insertions, 41 deletions
@@ -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 diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml index 1e907e20..02fe9633 100644 --- a/manual/qpdf-manual.xml +++ b/manual/qpdf-manual.xml @@ -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> @@ -976,14 +1026,6 @@ outfile.pdf</option> </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> <para> @@ -1013,14 +1055,6 @@ outfile.pdf</option> </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> <para> @@ -1143,17 +1177,6 @@ outfile.pdf</option> 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 Acrobat 6. Some older PDF viewers may not support files with @@ -1178,18 +1201,6 @@ outfile.pdf</option> 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, by default, stream data is uncompressed, content streams are diff --git a/qpdf/qpdf.cc b/qpdf/qpdf.cc index 575a046b..97d3a3e7 100644 --- a/qpdf/qpdf.cc +++ b/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\ |