From ad7e7bd692b9b8848f8d014f8fdd4fe305c4ffa2 Mon Sep 17 00:00:00 2001
From: m-holger <m.holger@qpdf.org>
Date: Thu, 20 Feb 2025 12:25:13 +0000
Subject: [PATCH] Deprecate QPDFTokenizer push mode

---
 include/qpdf/QPDFTokenizer.hh | 10 +++++-----
 manual/release-notes.rst      | 12 +++++++++++-
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/include/qpdf/QPDFTokenizer.hh b/include/qpdf/QPDFTokenizer.hh
index b047dc3..1633971 100644
--- a/include/qpdf/QPDFTokenizer.hh
+++ b/include/qpdf/QPDFTokenizer.hh
@@ -145,11 +145,11 @@ class QPDFTokenizer
 
     // Push mode:
 
+    // deprecated, please see <https:manual.qpdf.org/release-notes.html#r12-0-0-deprecate>
+
     // Keep presenting characters with presentCharacter() and presentEOF() and calling getToken()
     // until getToken() returns true. When it does, be sure to check unread_ch and to unread ch if
-    // it is true.
-
-    // It these are called when a token is available, an exception will be thrown.
+    // it is true. If these are called when a token is available, an exception will be thrown.
     QPDF_DLL
     void presentCharacter(char ch);
     QPDF_DLL
@@ -164,8 +164,8 @@ class QPDFTokenizer
     // This function returns true of the current character is between tokens (i.e., white space that
     // is not part of a string) or is part of a comment.  A tokenizing filter can call this to
     // determine whether to output the character.
-    QPDF_DLL
-    bool betweenTokens();
+    [[deprecated("see <https:manual.qpdf.org/release-notes.html#r12-0-0-deprecate>")]] QPDF_DLL bool
+    betweenTokens();
 
     // Pull mode:
 
diff --git a/manual/release-notes.rst b/manual/release-notes.rst
index 61d23c2..c821ae4 100644
--- a/manual/release-notes.rst
+++ b/manual/release-notes.rst
@@ -10,6 +10,8 @@ more detail.
 
 .. x.y.z: not yet released
 
+.. _r12-0-0:
+
 12.0.0: not yet released
   - API: breaking changes
 
@@ -29,6 +31,13 @@ more detail.
     - ``QIntC.hh`` contained the typo ``substract`` in function names,
       which has been fixed to ``subtract``.
 
+.. _r12-0-0-deprecate:
+
+    - The following are believed to be not in use and have been deprecated.
+      If you are relying on them please open a `ticket <https://issues.qpdf.org>`__:
+
+      - All ``QPDFTokenizer`` push-mode methods.
+
   - Library Enhancements
 
     - ``QPDFObjectHandle`` supports move construction/assignment.
@@ -114,7 +123,7 @@ more detail.
     - Add ``QPDFObjectHandle operator bool``. The operator returns true
       if the object handle is initialized and is a replacement for the
       ``isInitialized`` method. For more details see the
-      `qpdf wiki <https://github.com/qpdf/qpdf/wiki/Use-of-default-constructed-object-handles-in-qpdf-to-indicate-failure-or-error>`__.
+      `qpdf wiki <https://wiki.qpdf.org/Use-of-default-constructed-object-handles-in-qpdf-to-indicate-failure-or-error>`__.
 
     - New C API function ``qpdf_oh_free_buffer`` to free malloc allocated
       buffers.
@@ -408,6 +417,7 @@ more detail.
       PDF files.
 
 11.3.0: February 25, 2023
+
   - CLI Enhancements
 
     - New option :qpdf:ref:`--remove-restrictions` removes security
--
libgit2 0.21.4