[libxml2] Improve documentation of globals

[Nick Wellnhofer <nwellnhof src gnome org>]

commit 3513d76aa299f3053b93a69ac3a7d59d1de03bd1
Author: Nick Wellnhofer <wellnhofer aevum de>
Date:   Wed Aug 24 02:18:50 2022 +0200

    Improve documentation of globals
    
    Document more global variables as deprecated. Some of the variables
    don't generate deprecation warnings yet, but they shouldn't be used in
    new code.

 doc/devhelp/libxml2-globals.html | 20 ++++++++++----------
 doc/libxml2-api.xml              | 28 ++++++++++++++++++----------
 globals.c                        | 35 ++++++++++++++++++++++++++++++++++-
 3 files changed, 62 insertions(+), 21 deletions(-)
---
diff --git a/doc/devhelp/libxml2-globals.html b/doc/devhelp/libxml2-globals.html
index 05f9c090..9f4e6de8 100644
--- a/doc/devhelp/libxml2-globals.html
+++ b/doc/devhelp/libxml2-globals.html
@@ -166,11 +166,11 @@ const char *      <a href="#xmlThrDefTreeIndentString">xmlThrDefTreeIndentString</a>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlDeregisterNodeDefaultValue">Variable 
</a>xmlDeregisterNodeDefaultValue</h3><pre class="programlisting"><a 
href="libxml2-globals.html#xmlDeregisterNodeFunc">xmlDeregisterNodeFunc</a> xmlDeregisterNodeDefaultValue;
-</pre><p/>
+</pre><p>DEPRECATED: Don't use</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlDoValidityCheckingDefaultValue">Variable 
</a>xmlDoValidityCheckingDefaultValue</h3><pre class="programlisting">int xmlDoValidityCheckingDefaultValue;
-</pre><p>Global setting, indicate that the parser should work in validating mode. Disabled by default.</p>
+</pre><p>DEPRECATED: Use the modern options API with XML_PARSE_DTDVALID. Global setting, indicate that the 
parser should work in validating mode. Disabled by default.</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlFree">Variable </a>xmlFree</h3><pre 
class="programlisting"><a href="libxml2-xmlmemory.html#xmlFreeFunc">xmlFreeFunc</a> xmlFree;
@@ -186,7 +186,7 @@ const char *        <a href="#xmlThrDefTreeIndentString">xmlThrDefTreeIndentString</a>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlGetWarningsDefaultValue">Variable 
</a>xmlGetWarningsDefaultValue</h3><pre class="programlisting">int xmlGetWarningsDefaultValue;
-</pre><p>Global setting, indicate that the parser should provide warnings. Activated by default.</p>
+</pre><p>DEPRECATED: Don't use Global setting, indicate that the DTD validation should provide warnings. 
Activated by default.</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlIndentTreeOutput">Variable 
</a>xmlIndentTreeOutput</h3><pre class="programlisting">int xmlIndentTreeOutput;
@@ -194,7 +194,7 @@ const char *        <a href="#xmlThrDefTreeIndentString">xmlThrDefTreeIndentString</a>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlKeepBlanksDefaultValue">Variable 
</a>xmlKeepBlanksDefaultValue</h3><pre class="programlisting">int xmlKeepBlanksDefaultValue;
-</pre><p>Global setting, indicate that the parser should keep all blanks nodes found in the content 
Activated by default, this is actually needed to have the parser conformant to the XML Recommendation, 
however the option is kept for some applications since this was libxml1 default behaviour.</p>
+</pre><p>DEPRECATED: Use the modern options API with XML_PARSE_NOBLANKS. Global setting, indicate that the 
parser should keep all blanks nodes found in the content Activated by default, this is actually needed to 
have the parser conformant to the XML Recommendation, however the option is kept for some applications since 
this was libxml1 default behaviour.</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlLastError">Variable </a>xmlLastError</h3><pre 
class="programlisting"><a href="libxml2-xmlerror.html#xmlError">xmlError</a> xmlLastError;
@@ -206,7 +206,7 @@ const char *        <a href="#xmlThrDefTreeIndentString">xmlThrDefTreeIndentString</a>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlLoadExtDtdDefaultValue">Variable 
</a>xmlLoadExtDtdDefaultValue</h3><pre class="programlisting">int xmlLoadExtDtdDefaultValue;
-</pre><p>Global setting, indicate that the parser should load DTD while not validating. Disabled by 
default.</p>
+</pre><p>DEPRECATED: Use the modern options API with XML_PARSE_DTDLOAD. Global setting, indicate that the 
parser should load DTD while not validating. Disabled by default.</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlMalloc">Variable </a>xmlMalloc</h3><pre 
class="programlisting"><a href="libxml2-xmlmemory.html#xmlMallocFunc">xmlMallocFunc</a> xmlMalloc;
@@ -222,15 +222,15 @@ const char *      <a href="#xmlThrDefTreeIndentString">xmlThrDefTreeIndentString</a>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlOutputBufferCreateFilenameValue">Variable 
</a>xmlOutputBufferCreateFilenameValue</h3><pre class="programlisting"><a 
href="libxml2-globals.html#xmlOutputBufferCreateFilenameFunc">xmlOutputBufferCreateFilenameFunc</a> 
xmlOutputBufferCreateFilenameValue;
-</pre><p/>
+</pre><p>DEPRECATED: Don't use</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlParserDebugEntities">Variable 
</a>xmlParserDebugEntities</h3><pre class="programlisting">int xmlParserDebugEntities;
-</pre><p>Global setting, asking the parser to print out debugging information. while handling entities. 
Disabled by default</p>
+</pre><p>DEPRECATED: Don't use Global setting, asking the parser to print out debugging information. while 
handling entities. Disabled by default</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlParserInputBufferCreateFilenameValue">Variable 
</a>xmlParserInputBufferCreateFilenameValue</h3><pre class="programlisting"><a 
href="libxml2-globals.html#xmlParserInputBufferCreateFilenameFunc">xmlParserInputBufferCreateFilenameFunc</a> 
xmlParserInputBufferCreateFilenameValue;
-</pre><p/>
+</pre><p>DEPRECATED: Don't use</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlParserVersion">Variable 
</a>xmlParserVersion</h3><pre class="programlisting">const char * xmlParserVersion;
@@ -246,7 +246,7 @@ const char *        <a href="#xmlThrDefTreeIndentString">xmlThrDefTreeIndentString</a>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlRegisterNodeDefaultValue">Variable 
</a>xmlRegisterNodeDefaultValue</h3><pre class="programlisting"><a 
href="libxml2-globals.html#xmlRegisterNodeFunc">xmlRegisterNodeFunc</a> xmlRegisterNodeDefaultValue;
-</pre><p/>
+</pre><p>DEPRECATED: Don't use</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlSaveNoEmptyTags">Variable 
</a>xmlSaveNoEmptyTags</h3><pre class="programlisting">int xmlSaveNoEmptyTags;
@@ -262,7 +262,7 @@ const char *        <a href="#xmlThrDefTreeIndentString">xmlThrDefTreeIndentString</a>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlSubstituteEntitiesDefaultValue">Variable 
</a>xmlSubstituteEntitiesDefaultValue</h3><pre class="programlisting">int xmlSubstituteEntitiesDefaultValue;
-</pre><p>Global setting, indicate that the parser should not generate entity references but replace them 
with the actual content of the entity Disabled by default, this should be activated when using XPath since 
the XPath data model requires entities replacement and the XPath engine does not handle entities references 
transparently.</p>
+</pre><p>DEPRECATED: Use the modern options API with XML_PARSE_NOENT. Global setting, indicate that the 
parser should not generate entity references but replace them with the actual content of the entity Disabled 
by default, this should be activated when using XPath since the XPath data model requires entities 
replacement and the XPath engine does not handle entities references transparently.</p>
 </div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlTreeIndentString">Variable 
</a>xmlTreeIndentString</h3><pre class="programlisting">const char * xmlTreeIndentString;
diff --git a/doc/libxml2-api.xml b/doc/libxml2-api.xml
index 15d0d68b..a59d4dd3 100644
--- a/doc/libxml2-api.xml
+++ b/doc/libxml2-api.xml
@@ -6969,9 +6969,11 @@ Could we use @subtypes for this?'/>
     <variable name='xmlDefaultSAXLocator' file='globals' type='xmlSAXLocator'>
       <info>DEPRECATED: Don&apos;t use  The default SAX Locator { getPublicId, getSystemId, getLineNumber, 
getColumnNumber}</info>
     </variable>
-    <variable name='xmlDeregisterNodeDefaultValue' file='globals' type='xmlDeregisterNodeFunc'/>
+    <variable name='xmlDeregisterNodeDefaultValue' file='globals' type='xmlDeregisterNodeFunc'>
+      <info>DEPRECATED: Don&apos;t use</info>
+    </variable>
     <variable name='xmlDoValidityCheckingDefaultValue' file='globals' type='int'>
-      <info>Global setting, indicate that the parser should work in validating mode. Disabled by 
default.</info>
+      <info>DEPRECATED: Use the modern options API with XML_PARSE_DTDVALID.  Global setting, indicate that 
the parser should work in validating mode. Disabled by default.</info>
     </variable>
     <variable name='xmlFree' file='globals' type='xmlFreeFunc'>
       <info>@mem: an already allocated block of memory  The variable holding the libxml free() 
implementation</info>
@@ -6983,7 +6985,7 @@ Could we use @subtypes for this?'/>
       <info>Global setting passed to generic error callbacks</info>
     </variable>
     <variable name='xmlGetWarningsDefaultValue' file='globals' type='int'>
-      <info>Global setting, indicate that the parser should provide warnings. Activated by default.</info>
+      <info>DEPRECATED: Don&apos;t use  Global setting, indicate that the DTD validation should provide 
warnings. Activated by default.</info>
     </variable>
     <variable name='xmlIndentTreeOutput' file='globals' type='int'>
       <info>Global setting, asking the serializer to indent the output tree by default Enabled by 
default</info>
@@ -6996,14 +6998,14 @@ Could we use @subtypes for this?'/>
     <variable name='xmlIsIdeographicGroup' file='chvalid' type='const xmlChRangeGroup'/>
     <variable name='xmlIsPubidChar_tab' file='chvalid' type='const unsigned charxmlIsPubidChar_tab[256]'/>
     <variable name='xmlKeepBlanksDefaultValue' file='globals' type='int'>
-      <info>Global setting, indicate that the parser should keep all blanks nodes found in the content 
Activated by default, this is actually needed to have the parser conformant to the XML Recommendation, 
however the option is kept for some applications since this was libxml1 default behaviour.</info>
+      <info>DEPRECATED: Use the modern options API with XML_PARSE_NOBLANKS.  Global setting, indicate that 
the parser should keep all blanks nodes found in the content Activated by default, this is actually needed to 
have the parser conformant to the XML Recommendation, however the option is kept for some applications since 
this was libxml1 default behaviour.</info>
     </variable>
     <variable name='xmlLastError' file='globals' type='xmlError'/>
     <variable name='xmlLineNumbersDefaultValue' file='globals' type='int'>
       <info>DEPRECATED: The modern options API always enables line numbers.  Global setting, indicate that 
the parser should store the line number in the content field of elements in the DOM tree. Disabled by default 
since this may not be safe for old classes of application.</info>
     </variable>
     <variable name='xmlLoadExtDtdDefaultValue' file='globals' type='int'>
-      <info>Global setting, indicate that the parser should load DTD while not validating. Disabled by 
default.</info>
+      <info>DEPRECATED: Use the modern options API with XML_PARSE_DTDLOAD.  Global setting, indicate that 
the parser should load DTD while not validating. Disabled by default.</info>
     </variable>
     <variable name='xmlMalloc' file='globals' type='xmlMallocFunc'>
       <info>@size:  the size requested in bytes  The variable holding the libxml malloc() implementation  
Returns a pointer to the newly allocated block or NULL in case of error</info>
@@ -7014,11 +7016,15 @@ Could we use @subtypes for this?'/>
     <variable name='xmlMemStrdup' file='globals' type='xmlStrdupFunc'>
       <info>@str: a zero terminated string  The variable holding the libxml strdup() implementation  Returns 
the copy of the string or NULL in case of error</info>
     </variable>
-    <variable name='xmlOutputBufferCreateFilenameValue' file='globals' 
type='xmlOutputBufferCreateFilenameFunc'/>
+    <variable name='xmlOutputBufferCreateFilenameValue' file='globals' 
type='xmlOutputBufferCreateFilenameFunc'>
+      <info>DEPRECATED: Don&apos;t use</info>
+    </variable>
     <variable name='xmlParserDebugEntities' file='globals' type='int'>
-      <info>Global setting, asking the parser to print out debugging information. while handling entities. 
Disabled by default</info>
+      <info>DEPRECATED: Don&apos;t use  Global setting, asking the parser to print out debugging 
information. while handling entities. Disabled by default</info>
+    </variable>
+    <variable name='xmlParserInputBufferCreateFilenameValue' file='globals' 
type='xmlParserInputBufferCreateFilenameFunc'>
+      <info>DEPRECATED: Don&apos;t use</info>
     </variable>
-    <variable name='xmlParserInputBufferCreateFilenameValue' file='globals' 
type='xmlParserInputBufferCreateFilenameFunc'/>
     <variable name='xmlParserMaxDepth' file='parserInternals' type='unsigned int'>
       <info>arbitrary depth limit for the XML documents that we allow to process. This is not a limitation 
of the parser but a safety boundary feature. It can be disabled with the XML_PARSE_HUGE parser option.</info>
     </variable>
@@ -7031,7 +7037,9 @@ Could we use @subtypes for this?'/>
     <variable name='xmlRealloc' file='globals' type='xmlReallocFunc'>
       <info>@mem: an already allocated block of memory @size:  the new size requested in bytes  The variable 
holding the libxml realloc() implementation  Returns a pointer to the newly reallocated block or NULL in case 
of error</info>
     </variable>
-    <variable name='xmlRegisterNodeDefaultValue' file='globals' type='xmlRegisterNodeFunc'/>
+    <variable name='xmlRegisterNodeDefaultValue' file='globals' type='xmlRegisterNodeFunc'>
+      <info>DEPRECATED: Don&apos;t use</info>
+    </variable>
     <variable name='xmlSaveNoEmptyTags' file='globals' type='int'>
       <info>Global setting, asking the serializer to not output empty tags as &lt;empty/&gt; but 
&lt;empty&gt;&lt;/empty&gt;. those two forms are indistinguishable once parsed. Disabled by default</info>
     </variable>
@@ -7045,7 +7053,7 @@ Could we use @subtypes for this?'/>
       <info>Global setting passed to structured error callbacks</info>
     </variable>
     <variable name='xmlSubstituteEntitiesDefaultValue' file='globals' type='int'>
-      <info>Global setting, indicate that the parser should not generate entity references but replace them 
with the actual content of the entity Disabled by default, this should be activated when using XPath since 
the XPath data model requires entities replacement and the XPath engine does not handle entities references 
transparently.</info>
+      <info>DEPRECATED: Use the modern options API with XML_PARSE_NOENT.  Global setting, indicate that the 
parser should not generate entity references but replace them with the actual content of the entity Disabled 
by default, this should be activated when using XPath since the XPath data model requires entities 
replacement and the XPath engine does not handle entities references transparently.</info>
     </variable>
     <variable name='xmlTreeIndentString' file='globals' type='const char *'>
       <info>The string used to do one-level indent. By default is equal to &quot;  &quot; (two spaces)</info>
diff --git a/globals.c b/globals.c
index c2dfb623..5e50e038 100644
--- a/globals.c
+++ b/globals.c
@@ -205,6 +205,8 @@ int oldXMLWDcompatibility = 0; /* DEPRECATED */
 /**
  * xmlParserDebugEntities:
  *
+ * DEPRECATED: Don't use
+ *
  * Global setting, asking the parser to print out debugging information.
  * while handling entities.
  * Disabled by default
@@ -214,6 +216,8 @@ static int xmlParserDebugEntitiesThrDef = 0;
 /**
  * xmlDoValidityCheckingDefaultValue:
  *
+ * DEPRECATED: Use the modern options API with XML_PARSE_DTDVALID.
+ *
  * Global setting, indicate that the parser should work in validating mode.
  * Disabled by default.
  */
@@ -222,7 +226,9 @@ static int xmlDoValidityCheckingDefaultValueThrDef = 0;
 /**
  * xmlGetWarningsDefaultValue:
  *
- * Global setting, indicate that the parser should provide warnings.
+ * DEPRECATED: Don't use
+ *
+ * Global setting, indicate that the DTD validation should provide warnings.
  * Activated by default.
  */
 int xmlGetWarningsDefaultValue = 1;
@@ -230,6 +236,8 @@ static int xmlGetWarningsDefaultValueThrDef = 1;
 /**
  * xmlLoadExtDtdDefaultValue:
  *
+ * DEPRECATED: Use the modern options API with XML_PARSE_DTDLOAD.
+ *
  * Global setting, indicate that the parser should load DTD while not
  * validating.
  * Disabled by default.
@@ -261,6 +269,8 @@ static int xmlLineNumbersDefaultValueThrDef = 0;
 /**
  * xmlKeepBlanksDefaultValue:
  *
+ * DEPRECATED: Use the modern options API with XML_PARSE_NOBLANKS.
+ *
  * Global setting, indicate that the parser should keep all blanks
  * nodes found in the content
  * Activated by default, this is actually needed to have the parser
@@ -272,6 +282,8 @@ static int xmlKeepBlanksDefaultValueThrDef = 1;
 /**
  * xmlSubstituteEntitiesDefaultValue:
  *
+ * DEPRECATED: Use the modern options API with XML_PARSE_NOENT.
+ *
  * Global setting, indicate that the parser should not generate entity
  * references but replace them with the actual content of the entity
  * Disabled by default, this should be activated when using XPath since
@@ -281,14 +293,35 @@ static int xmlKeepBlanksDefaultValueThrDef = 1;
 int xmlSubstituteEntitiesDefaultValue = 0;
 static int xmlSubstituteEntitiesDefaultValueThrDef = 0;
 
+/**
+ * xmlRegisterNodeDefaultValue:
+ *
+ * DEPRECATED: Don't use
+ */
 xmlRegisterNodeFunc xmlRegisterNodeDefaultValue = NULL;
 static xmlRegisterNodeFunc xmlRegisterNodeDefaultValueThrDef = NULL;
+
+/**
+ * xmlDeregisterNodeDefaultValue:
+ *
+ * DEPRECATED: Don't use
+ */
 xmlDeregisterNodeFunc xmlDeregisterNodeDefaultValue = NULL;
 static xmlDeregisterNodeFunc xmlDeregisterNodeDefaultValueThrDef = NULL;
 
+/**
+ * xmlParserInputBufferCreateFilenameValue:
+ *
+ * DEPRECATED: Don't use
+ */
 xmlParserInputBufferCreateFilenameFunc xmlParserInputBufferCreateFilenameValue = NULL;
 static xmlParserInputBufferCreateFilenameFunc xmlParserInputBufferCreateFilenameValueThrDef = NULL;
 
+/**
+ * xmlOutputBufferCreateFilenameValue:
+ *
+ * DEPRECATED: Don't use
+ */
 xmlOutputBufferCreateFilenameFunc xmlOutputBufferCreateFilenameValue = NULL;
 static xmlOutputBufferCreateFilenameFunc xmlOutputBufferCreateFilenameValueThrDef = NULL;