From 48864b8d6eecc5bbd42029df0e2608621ce7d0bc Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Mon, 25 Dec 2017 18:42:33 -0500 Subject: Clarify documentation of advanced parsing options --- manual/qpdf-manual.xml | 89 ++++++++++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 39 deletions(-) (limited to 'manual/qpdf-manual.xml') 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, -- cgit v1.2.3-54-g00ecf