doc: Document option handling of deprecated "SAX1" functions

parser.c

@@ -11917,6 +11917,9 @@ xmlParseCtxtExternalEntity(xmlParserCtxt *ctxt, const xmlChar *URL,
  * An external general parsed entity is well-formed if it matches the
  * production labeled extParsedEnt.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlParseCtxtExternalEntity.
  *
  *     [78] extParsedEnt ::= TextDecl? content
@@ -11965,6 +11968,9 @@ xmlParseExternalEntity(xmlDoc *doc, xmlSAXHandler *sax, void *user_data,
  *     [43] content ::= (element | CharData | Reference | CDSect | PI |
  *                       Comment)*
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @param doc  the document the chunk pertains to (must not be NULL)
  * @param sax  the SAX handler block (possibly NULL)
  * @param user_data  The user data returned on SAX callbacks (possibly NULL)
@@ -12214,6 +12220,9 @@ xmlParseInNodeContext(xmlNode *node, const char *data, int datalen,
  * the parsed chunk is not well balanced, assuming the parsing succeeded to
  * some extent.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @param doc  the document the chunk pertains to (must not be NULL)
  * @param sax  the SAX handler block (possibly NULL)
  * @param user_data  The user data returned on SAX callbacks (possibly NULL)
@@ -12286,6 +12295,9 @@ error:
  *
  * This correspond to a "Well Balanced" chunk
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @param sax  the SAX handler block
  * @param filename  the filename
  * @returns the resulting document tree
@@ -12331,6 +12343,11 @@ xmlSAXParseEntity(xmlSAXHandler *sax, const char *filename) {
  *
  * This correspond to a "Well Balanced" chunk
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
+ * @deprecated Don't use.
+ *
  * @param filename  the filename
  * @returns the resulting document tree
  */
@@ -12458,6 +12475,9 @@ xmlCreateFileParserCtxt(const char *filename)
  * It use the given SAX function block to handle the parsing callback.
  * If sax is NULL, fallback to the default DOM tree building routines.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlNewSAXParserCtxt and #xmlCtxtReadFile.
  *
  * User data (void *) is stored within the parser context in the
@@ -12508,6 +12528,9 @@ xmlSAXParseFileWithData(xmlSAXHandler *sax, const char *filename,
  * It use the given SAX function block to handle the parsing callback.
  * If sax is NULL, fallback to the default DOM tree building routines.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlNewSAXParserCtxt and #xmlCtxtReadFile.
  *
  * @param sax  the SAX handler block
@@ -12528,6 +12551,9 @@ xmlSAXParseFile(xmlSAXHandler *sax, const char *filename,
  * In the case the document is not Well Formed, a attempt to build a
  * tree is tried anyway
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT | XML_PARSE_RECOVER.
+ *
  * @deprecated Use #xmlReadDoc with XML_PARSE_RECOVER.
  *
  * @param cur  a pointer to an array of xmlChar
@@ -12543,6 +12569,9 @@ xmlRecoverDoc(const xmlChar *cur) {
  * Parse an XML file and build a tree. Automatic support for ZLIB/Compress
  * compressed document is provided by default if found at compile-time.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlReadFile.
  *
  * @param filename  the filename
@@ -12561,6 +12590,9 @@ xmlParseFile(const char *filename) {
  * In the case the document is not Well Formed, it attempts to build
  * a tree anyway
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT | XML_PARSE_RECOVER.
+ *
  * @deprecated Use #xmlReadFile with XML_PARSE_RECOVER.
  *
  * @param filename  the filename
@@ -12607,6 +12639,9 @@ xmlSetupParserForBuffer(xmlParserCtxt *ctxt, const xmlChar* buffer,
  * Parse an XML file and call the given SAX handler routines.
  * Automatic support for ZLIB/Compress compressed document is provided
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlNewSAXParserCtxt and #xmlCtxtReadFile.
  *
  * @param sax  a SAX handler
@@ -12698,6 +12733,9 @@ xmlCreateMemoryParserCtxt(const char *buffer, int size) {
  * to handle the parsing callback. If sax is NULL, fallback to the default
  * DOM tree building routines.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlNewSAXParserCtxt and #xmlCtxtReadMemory.
  *
  * User data (void *) is stored within the parser context in the
@@ -12749,6 +12787,9 @@ xmlSAXParseMemoryWithData(xmlSAXHandler *sax, const char *buffer,
  * to handle the parsing callback. If sax is NULL, fallback to the default
  * DOM tree building routines.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlNewSAXParserCtxt and #xmlCtxtReadMemory.
  *
  * @param sax  the SAX handler block
@@ -12767,6 +12808,9 @@ xmlSAXParseMemory(xmlSAXHandler *sax, const char *buffer,
 /**
  * Parse an XML in-memory block and build a tree.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlReadMemory.
  *
  * @param buffer  an pointer to a char array
@@ -12783,6 +12827,9 @@ xmlDoc *xmlParseMemory(const char *buffer, int size) {
  * In the case the document is not Well Formed, an attempt to
  * build a tree is tried anyway
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT | XML_PARSE_RECOVER.
+ *
  * @deprecated Use #xmlReadMemory with XML_PARSE_RECOVER.
  *
  * @param buffer  an pointer to a char array
@@ -12797,6 +12844,9 @@ xmlDoc *xmlRecoverMemory(const char *buffer, int size) {
 /**
  * Parse an XML in-memory buffer and call the given SAX handler routines.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlNewSAXParserCtxt and #xmlCtxtReadMemory.
  *
  * @param sax  a SAX handler
@@ -12877,6 +12927,9 @@ xmlCreateDocParserCtxt(const xmlChar *str) {
  * It use the given SAX function block to handle the parsing callback.
  * If sax is NULL, fallback to the default DOM tree building routines.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlNewSAXParserCtxt and #xmlCtxtReadDoc.
  *
  * @param sax  the SAX handler block
@@ -12920,6 +12973,9 @@ xmlSAXParseDoc(xmlSAXHandler *sax, const xmlChar *cur, int recovery) {
 /**
  * Parse an XML in-memory document and build a tree.
  *
+ * This function uses deprecated global variables to set parser options
+ * which default to XML_PARSE_NODICT.
+ *
  * @deprecated Use #xmlReadDoc.
  *
  * @param cur  a pointer to an array of xmlChar