Clarify documentation of advanced parsing options

Jay Berkenbilt
1 parent 794b649e
Showing 3 changed files with 68 additions and 41 deletions
ChangeLog
manual/qpdf-manual.xml
qpdf/qpdf.cc
 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&lt;/option&gt;
     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&lt;/option&gt;
       </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&lt;/option&gt;
       </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&lt;/option&gt;
     You should not use this for &ldquo;production&rdquo; 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&lt;/option&gt;
     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
@@ -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\