Document new `inspection_mode` in design and release notes

Add details about the new `qpdf::global::inspection_mode` method to the design document, explaining its purpose, functionality, and limitations. Update release notes to highlight its introduction and describe the changes it brings for inspecting and repairing damaged PDF files.

Document new `inspection_mode` in design and release notes
Add details about the new `qpdf::global::inspection_mode` method to the design document, explaining its purpose, functionality, and limitations. Update release notes to highlight its introduction and describe the changes it brings for inspecting and repairing damaged PDF files.
m-holger
1 parent e848395d
Showing 2 changed files with 41 additions and 1 deletions
manual/design.rst
manual/release-notes.rst
@@ -35,6 +35,38 @@ behind the initial creation of qpdf. That said, qpdf is not a strict
 PDF checker. There are many ways in which a PDF file can be out of
 conformance to the spec that qpdf doesn't notice or report.
+.. _inspection-mode:
+
+Inspection Mode
+---------------
+
+The approach as described above has shifted somewhat over time for
+pragmatic reasons. A large number of essential repairs that can be
+carried out safely are now happening even with ``setAttemptRecovery(false)``.
+At the same time a number of minor infractions of the PDF standards are quietly
+dealt with to avoid creating distracting noise. This has been helpful to users
+who use qpdf to perform content-preserving transformations and who usually
+want qpdf to work reliably and to produce correct PDF output files that comply
+with the PDF standards even if the input files are somewhat less than perfect.
+
+However, there is another stated purpose of qpdf - to provide a tool for the
+study and analysis of PDF files. When used in this way, repairing the faults
+in input files or preventing the creation of unusable output files, often with
+unacceptable resource usage, is counter-productive rather than useful.
+
+To accommodate the needs of those who use qpdf as a tool for inspecting and
+investigating PDF files, qpdf version 12.3 introduced a special
+``ìnspection mode`` which is enabled using the
+``qpdf::global::options::inspection_mode`` function. In inspection mode, only a
+very limited set of basic operations is supported and a number of automatic
+repairs are disabled. Transformations of the input files such as linearizing files,
+creating object streams or encrypting files are not supported, as is the use of
+document and object helpers.
+
+Inspection mode is intended for manual investigations and repairs. As such,
+stability is less of a concern than for other uses of qpdf. The exact effect
+of specifying inspection mode will evolve from version to version.
+
 .. _design-goals:
 Design Goals
@@ -91,6 +91,14 @@ more detail.
   - Other enhancements
+    - Add new ``inspection mode`` to help with the inspection and manual repair
+      of damaged PDF files. In this mode some of the exceptions thrown if a PDF
+      file is damaged and unrepairable are replaced with warnings and some automatic
+      repairs are suppressed. Only a very limited range of operations are supported.
+      Inspection mode is selected with the new function
+      ``qpdf::global::options::inspection_mode``. For more detail see
+      :ref:`inspection-mode`.
+
     - ``QPDFWriter`` will no longer add filters when writing empty streams.
     - More sanity checks have been added when files with damaged xref tables
@@ -123,7 +131,7 @@ more detail.
       is the intended behaviour.
     - There has been some refactoring of stream filtering. These are optimized
-      for the common case where no user provided stream filters  are
+      for the common case where no user provided stream filters are
       registered by calling ``QPDF::registerStreamFilter``. If you are
       providing your own stream filters please open a ticket_.