From 66efa438bc228fbf937da84b2ca3be374125095f Mon Sep 17 00:00:00 2001 From: m-holger Date: Wed, 29 Oct 2025 13:03:54 +0000 Subject: [PATCH] Document new `inspection_mode` in design and release notes --- manual/design.rst | 32 ++++++++++++++++++++++++++++++++ manual/release-notes.rst | 10 +++++++++- 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/manual/design.rst b/manual/design.rst index ab73907..4a447a3 100644 --- a/manual/design.rst +++ b/manual/design.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 diff --git a/manual/release-notes.rst b/manual/release-notes.rst index 8e2c3c4..1b1530a 100644 --- a/manual/release-notes.rst +++ b/manual/release-notes.rst @@ -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_. -- libgit2 0.21.4