diff --git a/ChangeLog b/ChangeLog index 65b62352..245b96f2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ 2017-12-25 Jay Berkenbilt + * 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 to be bothered with. + + Advanced Parsing Options + + 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: + + + + + + Prevents qpdf from attempting to recover damaged files. + + + + + + + + Tells qpdf to ignore any cross-reference streams. + + + + + + + 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 will prevent qpdf from + attempting recovery. In this case, it will fail on the first + error that it encounters. + + + Ordinarily, qpdf reads cross-reference streams when they are + present in a PDF file. If + 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. + + Advanced Transformation Options @@ -975,14 +1025,6 @@ outfile.pdf - - - - - Prevents qpdf from attempting to recover damaged files. - - - @@ -1012,14 +1054,6 @@ outfile.pdf - - - - - Tells qpdf to ignore any cross-reference streams. - - - @@ -1142,17 +1176,6 @@ outfile.pdf who wish to study PDF content streams or to debug PDF content. You should not use this for “production” PDF files. - - 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 will prevent qpdf from - attempting recovery. In this case, it will fail on the first - error that it encounters. - 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 qpdf will also make sure the PDF version number in the header is at least 1.5. - - Ordinarily, qpdf reads cross-reference streams when they are - present in a PDF file. If - 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. - The flag turns on QDF mode, which changes some of the defaults described above. Specifically, in QDF mode, 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\