From 004fe9de53ec33133e6cafbe5850ebc9a1d1cdcf Mon Sep 17 00:00:00 2001
From: Nick Wellnhofer <wellnhofer@aevum.de>
Date: Sun, 20 Feb 2022 19:02:31 +0100
Subject: [PATCH] Deprecate IDREF-related functions in valid.h

These functions are only needed internally for validation.

xmlGetRefs is inherently unsafe because the ref table isn't updated
if attributes are removed (unlike the ids table).

None of the Ubuntu 20.04 packages depending on libxml2 use any of these
functions (except xmlFreeRefTable in libxslt), so it seems perfectly
safe to deprecate them.

Remove xmlIsRef and xmlRemoveRef from the Python bindings.
---
 include/libxml/valid.h |  5 +++++
 python/generator.py    |  7 +++++++
 valid.c                | 10 ++++++++++
 3 files changed, 22 insertions(+)

diff --git a/include/libxml/valid.h b/include/libxml/valid.h
index 15c9772c..3eaf84ad 100644
--- a/include/libxml/valid.h
+++ b/include/libxml/valid.h
@@ -283,20 +283,25 @@ XMLPUBFUN int XMLCALL
 					xmlAttrPtr attr);
 
 /* IDREFs */
+XML_DEPRECATED
 XMLPUBFUN xmlRefPtr XMLCALL
 		xmlAddRef	       (xmlValidCtxtPtr ctxt,
 					xmlDocPtr doc,
 					const xmlChar *value,
 					xmlAttrPtr attr);
+XML_DEPRECATED
 XMLPUBFUN void XMLCALL
 		xmlFreeRefTable	       (xmlRefTablePtr table);
+XML_DEPRECATED
 XMLPUBFUN int XMLCALL
 		xmlIsRef	       (xmlDocPtr doc,
 					xmlNodePtr elem,
 					xmlAttrPtr attr);
+XML_DEPRECATED
 XMLPUBFUN int XMLCALL
 		xmlRemoveRef	       (xmlDocPtr doc,
 					xmlAttrPtr attr);
+XML_DEPRECATED
 XMLPUBFUN xmlListPtr XMLCALL
 		xmlGetRefs	       (xmlDocPtr doc,
 					const xmlChar *ID);
diff --git a/python/generator.py b/python/generator.py
index 59d45e00..299bf2f2 100755
--- a/python/generator.py
+++ b/python/generator.py
@@ -289,7 +289,14 @@ skip_impl = (
     'xmlSaveFormatFileTo',
 )
 
+deprecated_funcs = {
+    'xmlIsRef': True,
+    'xmlRemoveRef': True,
+}
+
 def skip_function(name):
+    if name in deprecated_funcs:
+        return 1
     if name[0:12] == "xmlXPathWrap":
         return 1
     if name == "xmlFreeParserCtxt":
diff --git a/valid.c b/valid.c
index 23f868a3..d1df2d50 100644
--- a/valid.c
+++ b/valid.c
@@ -3000,6 +3000,8 @@ xmlDummyCompare(const void *data0 ATTRIBUTE_UNUSED,
  * @value:  the value name
  * @attr:  the attribute holding the Ref
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Register a new ref declaration
  *
  * Returns NULL if not, otherwise the new xmlRefPtr
@@ -3100,6 +3102,8 @@ failed:
  * xmlFreeRefTable:
  * @table:  An ref table
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Deallocate the memory used by an Ref hash table.
  */
 void
@@ -3113,6 +3117,8 @@ xmlFreeRefTable(xmlRefTablePtr table) {
  * @elem:  the element carrying the attribute
  * @attr:  the attribute
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Determine whether an attribute is of type Ref. In case we have DTD(s)
  * then this is simple, otherwise we use an heuristic: name Ref (upper
  * or lowercase).
@@ -3155,6 +3161,8 @@ xmlIsRef(xmlDocPtr doc, xmlNodePtr elem, xmlAttrPtr attr) {
  * @doc:  the document
  * @attr:  the attribute
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Remove the given attribute from the Ref table maintained internally.
  *
  * Returns -1 if the lookup failed and 0 otherwise
@@ -3211,6 +3219,8 @@ xmlRemoveRef(xmlDocPtr doc, xmlAttrPtr attr) {
  * @doc:  pointer to the document
  * @ID:  the ID value
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Find the set of references for the supplied ID.
  *
  * Returns NULL if not found, otherwise node set for the ID.