@img/sharp-libvips-dev 1.2.2 → 1.2.3

package/include/libxml2/libxml/parser.h

@@ -1,18 +1,22 @@
-/*
- * Summary: the core parser module
- * Description: Interfaces, constants and types related to the XML parser
+/**
+ * @file
+ * 
+ * @brief Validating XML 1.0 parser
+ * 
+ * Interfaces, constants and types related to the XML parser.
  *
- * Copy: See Copyright for the status of this software.
+ * @copyright See Copyright for the status of this software.
  *
- * Author: Daniel Veillard
+ * @author Daniel Veillard
  */
 
 #ifndef __XML_PARSER_H__
 #define __XML_PARSER_H__
 
-/** DOC_DISABLE */
 #include <libxml/xmlversion.h>
+/** @cond ignore */
 #define XML_TREE_INTERNALS
+/** @endcond */
 #include <libxml/tree.h>
 #undef XML_TREE_INTERNALS
 #include <libxml/dict.h>
@@ -27,82 +31,113 @@
 /* for compatibility */
 #include <libxml/SAX2.h>
 #include <libxml/threads.h>
-/** DOC_ENABLE */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * XML_DEFAULT_VERSION:
- *
  * The default version of XML used: 1.0
  */
 #define XML_DEFAULT_VERSION	"1.0"
 
+/**
+ * Status after parsing a document
+ */
 typedef enum {
+    /** not well-formed */
     XML_STATUS_NOT_WELL_FORMED          = (1 << 0),
+    /** not namespace-well-formed */
     XML_STATUS_NOT_NS_WELL_FORMED       = (1 << 1),
+    /** DTD validation failed */
     XML_STATUS_DTD_VALIDATION_FAILED    = (1 << 2),
+    /** catastrophic failure like OOM or I/O error */
     XML_STATUS_CATASTROPHIC_ERROR       = (1 << 3)
 } xmlParserStatus;
 
+/**
+ * Resource type for resource loaders
+ */
 typedef enum {
+    /** unknown */
     XML_RESOURCE_UNKNOWN = 0,
+    /** main document */
     XML_RESOURCE_MAIN_DOCUMENT,
+    /** external DTD */
     XML_RESOURCE_DTD,
+    /** external general entity */
     XML_RESOURCE_GENERAL_ENTITY,
+    /** external parameter entity */
     XML_RESOURCE_PARAMETER_ENTITY,
+    /** XIncluded document */
     XML_RESOURCE_XINCLUDE,
+    /** XIncluded text */
     XML_RESOURCE_XINCLUDE_TEXT
 } xmlResourceType;
 
+/**
+ * Flags for parser input
+ */
 typedef enum {
+    /** The input buffer won't be changed during parsing. */
     XML_INPUT_BUF_STATIC            = (1 << 1),
+    /** The input buffer is zero-terminated. (Note that the zero
+        byte shouldn't be included in buffer size.) */
     XML_INPUT_BUF_ZERO_TERMINATED   = (1 << 2),
+    /** Uncompress gzipped file input */
     XML_INPUT_UNZIP                 = (1 << 3),
-    XML_INPUT_NETWORK               = (1 << 4)
+    /** Allow network access. Unused internally. */
+    XML_INPUT_NETWORK               = (1 << 4),
+    /** Allow system catalog to resolve URIs. */
+    XML_INPUT_USE_SYS_CATALOG       = (1 << 5)
 } xmlParserInputFlags;
 
-/**
- * xmlParserInput:
- *
- * An xmlParserInput is an input flow for the XML processor.
- * Each entity parsed is associated an xmlParserInput (except the
- * few predefined ones). This is the case both for internal entities
- * - in which case the flow is already completely in memory - or
- * external entities - in which case we use the buf structure for
- * progressive reading and I18N conversions to the internal UTF-8 format.
- */
+/* Deprecated */
+typedef void (* xmlParserInputDeallocate)(xmlChar *str);
 
 /**
- * xmlParserInputDeallocate:
- * @str:  the string to deallocate
- *
- * Callback for freeing some parser input allocations.
+ * Parser input
  */
-typedef void (* xmlParserInputDeallocate)(xmlChar *str);
-
 struct _xmlParserInput {
     /* Input buffer */
-    xmlParserInputBufferPtr buf;
-    /* The file analyzed, if any */
+    xmlParserInputBuffer *buf XML_DEPRECATED_MEMBER;
+    /**
+     * @deprecated Use #xmlCtxtGetInputPosition
+     *
+     * The filename or URI, if any
+     */
     const char *filename;
     /* unused */
     const char *directory XML_DEPRECATED_MEMBER;
     /* Base of the array to parse */
     const xmlChar *base;
-    /* Current char being parsed */
+    /**
+     * @deprecated Use #xmlCtxtGetInputWindow
+     *
+     * Current char being parsed
+     */
     const xmlChar *cur;
     /* end of the array to parse */
     const xmlChar *end;
     /* unused */
     int length XML_DEPRECATED_MEMBER;
-    /* Current line */
+    /**
+     * @deprecated Use #xmlCtxtGetInputPosition
+     *
+     * Current line
+     */
     int line;
-    /* Current column */
+    /**
+     * @deprecated Use #xmlCtxtGetInputPosition
+     *
+     * Current column
+     */
     int col;
-    /* How many xmlChars already consumed */
+    /**
+     * @deprecated Use #xmlCtxtGetInputPosition
+     *
+     * How many xmlChars already consumed
+     */
     unsigned long consumed;
     /* function to deallocate the base */
     xmlParserInputDeallocate free XML_DEPRECATED_MEMBER;
@@ -112,21 +147,16 @@ struct _xmlParserInput {
     const xmlChar *version XML_DEPRECATED_MEMBER;
     /* Flags */
     int flags XML_DEPRECATED_MEMBER;
-    /* an unique identifier for the entity */
+    /* an unique identifier for the entity, unused internally */
     int id XML_DEPRECATED_MEMBER;
     /* unused */
     unsigned long parentConsumed XML_DEPRECATED_MEMBER;
     /* entity, if any */
-    xmlEntityPtr entity XML_DEPRECATED_MEMBER;
+    xmlEntity *entity XML_DEPRECATED_MEMBER;
 };
 
-/**
- * xmlParserNodeInfo:
- *
- * The parser can be asked to collect Node information, i.e. at what
- * place in the file they were detected.
- * NOTE: This is off by default and not very well tested.
- */
+/** @cond ignore */
+
 typedef struct _xmlParserNodeInfo xmlParserNodeInfo;
 typedef xmlParserNodeInfo *xmlParserNodeInfoPtr;
 
@@ -147,11 +177,8 @@ struct _xmlParserNodeInfoSeq {
   xmlParserNodeInfo* buffer;
 };
 
-/**
- * xmlParserInputState:
- *
- * The parser is now working also as a state based parser.
- * The recursive one use the state info for entities processing.
+/*
+ * Internal type
  */
 typedef enum {
     XML_PARSER_EOF = -1,	/* nothing is to be parsed */
@@ -175,19 +202,15 @@ typedef enum {
     XML_PARSER_XML_DECL         /* before XML decl (but after BOM) */
 } xmlParserInputState;
 
-/** DOC_DISABLE */
 /*
  * Internal bits in the 'loadsubset' context member
  */
 #define XML_DETECT_IDS		2
 #define XML_COMPLETE_ATTRS	4
 #define XML_SKIP_IDS		8
-/** DOC_ENABLE */
 
-/**
- * xmlParserMode:
- *
- * A parser can operate in various modes
+/*
+ * Internal type. Only XML_PARSE_READER is used.
  */
 typedef enum {
     XML_PARSE_UNKNOWN = 0,
@@ -202,93 +225,132 @@ typedef struct _xmlStartTag xmlStartTag;
 typedef struct _xmlParserNsData xmlParserNsData;
 typedef struct _xmlAttrHashBucket xmlAttrHashBucket;
 
+/** @endcond */
+
 /**
- * xmlResourceLoader:
- * @ctxt:  parser context
- * @url:  URL to load
- * @publicId:  publid ID from DTD (optional)
- * @type:  resource type
- * @flags:  flags
- * @out:  result pointer
- *
  * Callback for custom resource loaders.
  *
- * @flags can contain XML_INPUT_UNZIP and XML_INPUT_NETWORK.
+ * `flags` can contain XML_INPUT_UNZIP and XML_INPUT_NETWORK.
  *
- * On success, @out should be set to a new parser input object and
+ * The URL is resolved using XML catalogs before being passed to
+ * the callback.
+ *
+ * On success, `out` should be set to a new parser input object and
  * XML_ERR_OK should be returned.
  *
- * Returns an xmlParserErrors code.
+ * @param ctxt  parser context
+ * @param url  URL or system ID to load
+ * @param publicId  publid ID from DTD (optional)
+ * @param type  resource type
+ * @param flags  flags
+ * @param out  result pointer
+ * @returns an xmlParserErrors code.
  */
 typedef xmlParserErrors
 (*xmlResourceLoader)(void *ctxt, const char *url, const char *publicId,
                      xmlResourceType type, xmlParserInputFlags flags,
-                     xmlParserInputPtr *out);
+                     xmlParserInput **out);
 
 /**
- * xmlParserCtxt:
- *
- * The parser context.
- * NOTE This doesn't completely define the parser state, the (current ?)
- *      design of the parser uses recursive function calls since this allow
- *      and easy mapping from the production rules of the specification
- *      to the actual code. The drawback is that the actual function call
- *      also reflect the parser state. However most of the parsing routines
- *      takes as the only argument the parser context pointer, so migrating
- *      to a state based parser for progressive parsing shouldn't be too hard.
+ * Parser context
  */
 struct _xmlParserCtxt {
-    /* The SAX handler */
+    /**
+     * @deprecated Use xmlCtxtGetSaxHandler() and
+     * xmlCtxtSetSaxHandler().
+     *
+     * the SAX handler
+     */
     struct _xmlSAXHandler *sax;
-    /* For SAX interface only, used by DOM build */
+    /**
+     * @deprecated Use #xmlCtxtGetUserData
+     *
+     * user data for SAX interface, defaults to the context itself
+     */
     void *userData;
-    /* the document being built */
-    xmlDocPtr myDoc;
-    /* is the document well formed */
+    /**
+     * @deprecated Use xmlCtxtGetDocument()
+     *
+     * the document being built
+     */
+    xmlDoc *myDoc;
+    /**
+     * @deprecated Use xmlCtxtGetStatus()
+     *
+     * is the document well formed?
+     */
     int wellFormed;
-    /* shall we replace entities ? */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_NOENT
+     *
+     * shall we replace entities?
+     */
     int replaceEntities XML_DEPRECATED_MEMBER;
-    /* the XML version string */
-    const xmlChar *version;
-    /* the declared encoding, if any */
-    const xmlChar *encoding;
-    /* standalone document */
+    /**
+     * @deprecated Use xmlCtxtGetVersion()
+     *
+     * the XML version string
+     */
+    xmlChar *version;
+    /**
+     * @deprecated Use xmlCtxtGetDeclaredEncoding()
+     *
+     * the declared encoding, if any
+     */
+    xmlChar *encoding;
+    /**
+     * @deprecated Use xmlCtxtGetStandalone()
+     *
+     * standalone document
+     */
     int standalone;
 
-    /* an HTML(1) document
-     * 3 is HTML after <head>
-     * 10 is HTML after <body>
+    /**
+     * @deprecated Use xmlCtxtIsHtml()
+     *
+     * non-zero for HTML documents, actually an htmlInsertMode
      */
     int html;
 
     /* Input stream stack */
 
-    /* Current input stream */
-    xmlParserInputPtr input;
+    /**
+     * Current input stream
+     */
+    /* TODO: Add accessors, see issue #762 */
+    xmlParserInput *input;
     /* Number of current input streams */
     int inputNr;
     /* Max number of input streams */
     int inputMax XML_DEPRECATED_MEMBER;
     /* stack of inputs */
-    xmlParserInputPtr *inputTab;
+    xmlParserInput **inputTab;
 
     /* Node analysis stack only used for DOM building */
 
-    /* Current parsed Node */
-    xmlNodePtr node;
+    /**
+     * @deprecated Use #xmlCtxtGetNode
+     *
+     * The current element.
+     */
+    xmlNode *node;
     /* Depth of the parsing stack */
     int nodeNr XML_DEPRECATED_MEMBER;
     /* Max depth of the parsing stack */
     int nodeMax XML_DEPRECATED_MEMBER;
     /* array of nodes */
-    xmlNodePtr *nodeTab XML_DEPRECATED_MEMBER;
+    xmlNode **nodeTab XML_DEPRECATED_MEMBER;
 
     /* Whether node info should be kept */
     int record_info;
     /* info about each node parsed */
     xmlParserNodeInfoSeq node_seq XML_DEPRECATED_MEMBER;
 
-    /* error code */
+    /**
+     * @deprecated Use xmlCtxtGetLastError()
+     *
+     * error code
+     */
     int errNo;
 
     /* reference and external subset */
@@ -298,11 +360,23 @@ struct _xmlParserCtxt {
     /* unused */
     int external XML_DEPRECATED_MEMBER;
 
-    /* is the document valid */
+    /**
+     * @deprecated Use xmlCtxtGetStatus()
+     *
+     * is the document valid
+     */
     int valid;
-    /* shall we try to validate ? */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_DTDVALID
+     *
+     * shall we try to validate?
+     */
     int validate XML_DEPRECATED_MEMBER;
-    /* The validity context */
+    /**
+     * @deprecated Use xmlCtxtGetValidCtxt()
+     *
+     * The validity context
+     */
     xmlValidCtxt vctxt;
 
     /* push parser state */
@@ -310,7 +384,12 @@ struct _xmlParserCtxt {
     /* unused */
     int token XML_DEPRECATED_MEMBER;
 
-    /* unused internally, still used downstream */
+    /**
+     * @deprecated Don't use
+     *
+     * The main document URI, if available, with its last
+     * component stripped.
+     */
     char *directory;
 
     /* Node name stack */
@@ -328,17 +407,49 @@ struct _xmlParserCtxt {
     long nbChars XML_DEPRECATED_MEMBER;
     /* used by progressive parsing lookup */
     long checkIndex XML_DEPRECATED_MEMBER;
-    /* ugly but ... */
+    /**
+     * @deprecated Use inverted xmlParserOption XML_PARSE_NOBLANKS
+     *
+     * ugly but ...
+     */
     int keepBlanks XML_DEPRECATED_MEMBER;
-    /* SAX callbacks are disabled */
-    int disableSAX;
-    /* Parsing is in int 1/ext 2 subset */
+    /**
+     * @deprecated Use xmlCtxtIsStopped()
+     *
+     * SAX callbacks are disabled
+     */
+    int disableSAX XML_DEPRECATED_MEMBER;
+    /**
+     * @deprecated Use xmlCtxtIsInSubset
+     *
+     * Set if DTD content is parsed.
+     *
+     * - 0: not in DTD
+     * - 1: in internal DTD subset
+     * - 2: in external DTD subset
+     */
     int inSubset;
-    /* name of subset */
+    /**
+     * @deprecated Use the `name` argument of the
+     * `internalSubset` SAX callback or #xmlCtxtGetDocTypeDecl
+     *
+     * Name of the internal subset (root element type).
+     */
     const xmlChar *intSubName;
-    /* URI of external subset */
+    /**
+     * @deprecated Use the `systemId` argument of the
+     * `internalSubset` SAX callback or #xmlCtxtGetDocTypeDecl
+     *
+     * System identifier (URI) of external the subset.
+     */
     xmlChar *extSubURI;
-    /* SYSTEM ID of external subset */
+    /**
+     * @deprecated Use the `publicId` argument of the
+     * `internalSubset` SAX callback or #xmlCtxtGetDocTypeDecl
+     *
+     * This member is MISNAMED. It contains the *public* identifier
+     * of the external subset.
+     */
     xmlChar *extSubSystem;
 
     /* xml:space values */
@@ -355,30 +466,61 @@ struct _xmlParserCtxt {
     /* to prevent entity substitution loops */
     int depth XML_DEPRECATED_MEMBER;
     /* unused */
-    xmlParserInputPtr entity XML_DEPRECATED_MEMBER;
+    xmlParserInput *entity XML_DEPRECATED_MEMBER;
     /* unused */
     int charset XML_DEPRECATED_MEMBER;
-    /* Those two fields are there to */
+    /* Those two fields are there to speed up large node parsing */
     int nodelen XML_DEPRECATED_MEMBER;
-    /* Speed up large node parsing */
     int nodemem XML_DEPRECATED_MEMBER;
-    /* signal pedantic warnings */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_PEDANTIC
+     *
+     * signal pedantic warnings
+     */
     int pedantic XML_DEPRECATED_MEMBER;
-    /* For user data, libxml won't touch it */
+    /**
+     * @deprecated Use xmlCtxtGetPrivate() and xmlCtxtSetPrivate()
+     *
+     * For user data, libxml won't touch it
+     */
     void *_private;
-
-    /* should the external subset be loaded */
-    int loadsubset;
-    /* set line number in element content */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_DTDLOAD,
+     * XML_PARSE_DTDATTR or XML_PARSE_SKIP_IDS.
+     *
+     * Control loading of the external subset and handling of IDs.
+     * Other options like `validate` can override this value.
+     *
+     * - 0: The default behavior is to process IDs and to ignore
+     *   the external subset.
+     * - XML_DETECT_IDS: Load external subset. This flag is
+     *   misnamed. ID handling is only controlled by XML_SKIP_IDS.
+     * - XML_COMPLETE_ATTRS: Load external subset and process
+     *   default attributes.
+     * - XML_SKIP_IDS: Ignore IDs.
+     */
+    int loadsubset XML_DEPRECATED_MEMBER;
+    /* unused */
     int linenumbers XML_DEPRECATED_MEMBER;
-    /* document's own catalog */
+    /**
+     * @deprecated Use xmlCtxtGetCatalogs() and xmlCtxtSetCatalogs()
+     *
+     * document's own catalog
+     */
     void *catalogs XML_DEPRECATED_MEMBER;
-    /* run in recovery mode */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_RECOVER
+     * run in recovery mode
+     */
     int recovery XML_DEPRECATED_MEMBER;
     /* unused */
     int progressive XML_DEPRECATED_MEMBER;
-    /* dictionary for the parser */
-    xmlDictPtr dict;
+    /**
+     * @deprecated Use xmlCtxtGetDict() and xmlCtxtSetDict()
+     *
+     * dictionary for the parser
+     */
+    xmlDict *dict;
     /* array for the attributes callbacks */
     const xmlChar **atts XML_DEPRECATED_MEMBER;
     /* the size of the array */
@@ -410,30 +552,46 @@ struct _xmlParserCtxt {
     /* array of data for push */
     xmlStartTag *pushTab XML_DEPRECATED_MEMBER;
     /* defaulted attributes if any */
-    xmlHashTablePtr attsDefault XML_DEPRECATED_MEMBER;
+    xmlHashTable *attsDefault XML_DEPRECATED_MEMBER;
     /* non-CDATA attributes if any */
-    xmlHashTablePtr attsSpecial XML_DEPRECATED_MEMBER;
-    /* is the document XML Namespace okay */
+    xmlHashTable *attsSpecial XML_DEPRECATED_MEMBER;
+
+    /**
+     * @deprecated Use xmlCtxtGetStatus()
+     *
+     * is the document XML Namespace okay
+     */
     int nsWellFormed;
-    /* Extra options */
+    /**
+     * @deprecated Use xmlCtxtGetOptions()
+     *
+     * Extra options
+     */
     int options;
 
+    /**
+     * @deprecated Use inverted xmlParserOption XML_PARSE_NODICT
+     *
+     * Use dictionary names for the tree
+     */
+    int dictNames XML_DEPRECATED_MEMBER;
+
     /*
      * Those fields are needed only for streaming parsing so far
      */
 
-    /* Use dictionary names for the tree */
-    int dictNames XML_DEPRECATED_MEMBER;
     /* number of freed element nodes */
     int freeElemsNr XML_DEPRECATED_MEMBER;
     /* List of freed element nodes */
-    xmlNodePtr freeElems XML_DEPRECATED_MEMBER;
+    xmlNode *freeElems XML_DEPRECATED_MEMBER;
     /* number of freed attributes nodes */
     int freeAttrsNr XML_DEPRECATED_MEMBER;
     /* List of freed attributes nodes */
-    xmlAttrPtr freeAttrs XML_DEPRECATED_MEMBER;
+    xmlAttr *freeAttrs XML_DEPRECATED_MEMBER;
 
-    /*
+    /**
+     * @deprecated Use xmlCtxtGetLastError()
+     *
      * the complete error information for the last error.
      */
     xmlError lastError XML_DEPRECATED_MEMBER;
@@ -486,8 +644,6 @@ struct _xmlParserCtxt {
 };
 
 /**
- * xmlSAXLocator:
- *
  * A SAX Locator.
  */
 struct _xmlSAXLocator {
@@ -498,88 +654,70 @@ struct _xmlSAXLocator {
 };
 
 /**
- * xmlSAXHandler:
+ * SAX callback to resolve external entities.
  *
- * A SAX handler is bunch of callbacks called by the parser when processing
- * of the input generate data or structure information.
- */
-
-/**
- * resolveEntitySAXFunc:
- * @ctx:  the user data (XML parser context)
- * @publicId: The public ID of the entity
- * @systemId: The system ID of the entity
- *
- * Callback:
- * The entity loader, to control the loading of external entities,
- * the application can either:
- *    - override this resolveEntity() callback in the SAX block
- *    - or better use the xmlSetExternalEntityLoader() function to
- *      set up it's own entity resolution routine
+ * This is only used to load DTDs. The preferred way to install
+ * custom resolvers is #xmlCtxtSetResourceLoader.
  *
- * Returns the xmlParserInputPtr if inlined or NULL for DOM behaviour.
+ * @param ctx  the user data (XML parser context)
+ * @param publicId  The public identifier of the entity
+ * @param systemId  The system identifier of the entity (URL)
+ * @returns the xmlParserInput if inlined or NULL for DOM behaviour.
  */
-typedef xmlParserInputPtr (*resolveEntitySAXFunc) (void *ctx,
+typedef xmlParserInput *(*resolveEntitySAXFunc) (void *ctx,
 				const xmlChar *publicId,
 				const xmlChar *systemId);
 /**
- * internalSubsetSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  the root element name
- * @ExternalID:  the external ID
- * @SystemID:  the SYSTEM ID (e.g. filename or URL)
+ * SAX callback for the internal subset.
  *
- * Callback on internal subset declaration.
+ * @param ctx  the user data (XML parser context)
+ * @param name  the root element name
+ * @param publicId  the public identifier
+ * @param systemId  the system identifier (e.g. filename or URL)
  */
 typedef void (*internalSubsetSAXFunc) (void *ctx,
 				const xmlChar *name,
-				const xmlChar *ExternalID,
-				const xmlChar *SystemID);
+				const xmlChar *publicId,
+				const xmlChar *systemId);
 /**
- * externalSubsetSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  the root element name
- * @ExternalID:  the external ID
- * @SystemID:  the SYSTEM ID (e.g. filename or URL)
+ * SAX callback for the external subset.
  *
- * Callback on external subset declaration.
+ * @param ctx  the user data (XML parser context)
+ * @param name  the root element name
+ * @param publicId  the public identifier
+ * @param systemId  the system identifier (e.g. filename or URL)
  */
 typedef void (*externalSubsetSAXFunc) (void *ctx,
 				const xmlChar *name,
-				const xmlChar *ExternalID,
-				const xmlChar *SystemID);
+				const xmlChar *publicId,
+				const xmlChar *systemId);
 /**
- * getEntitySAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name: The entity name
- *
- * Get an entity by name.
+ * SAX callback to look up a general entity by name.
  *
- * Returns the xmlEntityPtr if found.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The entity name
+ * @returns the xmlEntity if found.
  */
-typedef xmlEntityPtr (*getEntitySAXFunc) (void *ctx,
+typedef xmlEntity *(*getEntitySAXFunc) (void *ctx,
 				const xmlChar *name);
 /**
- * getParameterEntitySAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name: The entity name
- *
- * Get a parameter entity by name.
+ * SAX callback to look up a parameter entity by name.
  *
- * Returns the xmlEntityPtr if found.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The entity name
+ * @returns the xmlEntity if found.
  */
-typedef xmlEntityPtr (*getParameterEntitySAXFunc) (void *ctx,
+typedef xmlEntity *(*getParameterEntitySAXFunc) (void *ctx,
 				const xmlChar *name);
 /**
- * entityDeclSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  the entity name
- * @type:  the entity type
- * @publicId: The public ID of the entity
- * @systemId: The system ID of the entity
- * @content: the entity value (without processing).
+ * SAX callback for entity declarations.
  *
- * An entity definition has been parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param name  the entity name
+ * @param type  the entity type
+ * @param publicId  The public ID of the entity
+ * @param systemId  The system ID of the entity
+ * @param content  the entity value (without processing).
  */
 typedef void (*entityDeclSAXFunc) (void *ctx,
 				const xmlChar *name,
@@ -588,29 +726,27 @@ typedef void (*entityDeclSAXFunc) (void *ctx,
 				const xmlChar *systemId,
 				xmlChar *content);
 /**
- * notationDeclSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name: The name of the notation
- * @publicId: The public ID of the entity
- * @systemId: The system ID of the entity
+ * SAX callback for notation declarations.
  *
- * What to do when a notation declaration has been parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The name of the notation
+ * @param publicId  The public ID of the notation
+ * @param systemId  The system ID of the notation
  */
 typedef void (*notationDeclSAXFunc)(void *ctx,
 				const xmlChar *name,
 				const xmlChar *publicId,
 				const xmlChar *systemId);
 /**
- * attributeDeclSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @elem:  the name of the element
- * @fullname:  the attribute name
- * @type:  the attribute type
- * @def:  the type of default value
- * @defaultValue: the attribute default value
- * @tree:  the tree of enumerated value set
+ * SAX callback for attribute declarations.
  *
- * An attribute definition has been parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param elem  the name of the element
+ * @param fullname  the attribute name
+ * @param type  the attribute type
+ * @param def  the type of default value
+ * @param defaultValue  the attribute default value
+ * @param tree  the tree of enumerated value set
  */
 typedef void (*attributeDeclSAXFunc)(void *ctx,
 				const xmlChar *elem,
@@ -618,29 +754,27 @@ typedef void (*attributeDeclSAXFunc)(void *ctx,
 				int type,
 				int def,
 				const xmlChar *defaultValue,
-				xmlEnumerationPtr tree);
+				xmlEnumeration *tree);
 /**
- * elementDeclSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  the element name
- * @type:  the element type
- * @content: the element value tree
+ * SAX callback for element declarations.
  *
- * An element definition has been parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param name  the element name
+ * @param type  the element type
+ * @param content  the element value tree
  */
 typedef void (*elementDeclSAXFunc)(void *ctx,
 				const xmlChar *name,
 				int type,
-				xmlElementContentPtr content);
+				xmlElementContent *content);
 /**
- * unparsedEntityDeclSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name: The name of the entity
- * @publicId: The public ID of the entity
- * @systemId: The system ID of the entity
- * @notationName: the name of the notation
+ * SAX callback for unparsed entity declarations.
  *
- * What to do when an unparsed entity declaration is parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The name of the entity
+ * @param publicId  The public ID of the entity
+ * @param systemId  The system ID of the entity
+ * @param notationName  the name of the notation
  */
 typedef void (*unparsedEntityDeclSAXFunc)(void *ctx,
 				const xmlChar *name,
@@ -648,185 +782,163 @@ typedef void (*unparsedEntityDeclSAXFunc)(void *ctx,
 				const xmlChar *systemId,
 				const xmlChar *notationName);
 /**
- * setDocumentLocatorSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @loc: A SAX Locator
+ * This callback receives the "document locator" at startup,
+ * which is always the global xmlDefaultSAXLocator.
  *
- * Receive the document locator at startup, actually xmlDefaultSAXLocator.
- * Everything is available on the context, so this is useless in our case.
+ * Everything is available on the context, so this is useless in
+ * our case.
+ *
+ * @param ctx  the user data (XML parser context)
+ * @param loc  A SAX Locator
  */
 typedef void (*setDocumentLocatorSAXFunc) (void *ctx,
-				xmlSAXLocatorPtr loc);
+				xmlSAXLocator *loc);
 /**
- * startDocumentSAXFunc:
- * @ctx:  the user data (XML parser context)
+ * SAX callback for start of document.
  *
- * Called when the document start being processed.
+ * @param ctx  the user data (XML parser context)
  */
 typedef void (*startDocumentSAXFunc) (void *ctx);
 /**
- * endDocumentSAXFunc:
- * @ctx:  the user data (XML parser context)
+ * SAX callback for end of document.
  *
- * Called when the document end has been detected.
+ * @param ctx  the user data (XML parser context)
  */
 typedef void (*endDocumentSAXFunc) (void *ctx);
 /**
- * startElementSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  The element name, including namespace prefix
- * @atts:  An array of name/value attributes pairs, NULL terminated
+ * SAX callback for start tags.
  *
- * Called when an opening tag has been processed.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The element name, including namespace prefix
+ * @param atts  An array of name/value attributes pairs, NULL terminated
  */
 typedef void (*startElementSAXFunc) (void *ctx,
 				const xmlChar *name,
 				const xmlChar **atts);
 /**
- * endElementSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  The element name
+ * SAX callback for end tags.
  *
- * Called when the end of an element has been detected.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The element name
  */
 typedef void (*endElementSAXFunc) (void *ctx,
 				const xmlChar *name);
 /**
- * attributeSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  The attribute name, including namespace prefix
- * @value:  The attribute value
+ * Callback for attributes.
+ *
+ * @deprecated This typedef is unused.
  *
- * Handle an attribute that has been read by the parser.
- * The default handling is to convert the attribute into an
- * DOM subtree and past it in a new xmlAttr element added to
- * the element.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The attribute name, including namespace prefix
+ * @param value  The attribute value
  */
 typedef void (*attributeSAXFunc) (void *ctx,
 				const xmlChar *name,
 				const xmlChar *value);
 /**
- * referenceSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @name:  The entity name
+ * SAX callback for entity references.
  *
- * Called when an entity reference is detected.
+ * @param ctx  the user data (XML parser context)
+ * @param name  The entity name
  */
 typedef void (*referenceSAXFunc) (void *ctx,
 				const xmlChar *name);
 /**
- * charactersSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @ch:  a xmlChar string
- * @len: the number of xmlChar
+ * SAX callback for character data.
  *
- * Receiving some chars from the parser.
+ * @param ctx  the user data (XML parser context)
+ * @param ch  a xmlChar string
+ * @param len  the number of xmlChar
  */
 typedef void (*charactersSAXFunc) (void *ctx,
 				const xmlChar *ch,
 				int len);
 /**
- * ignorableWhitespaceSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @ch:  a xmlChar string
- * @len: the number of xmlChar
+ * SAX callback for "ignorable" whitespace.
  *
- * Receiving some ignorable whitespaces from the parser.
- * UNUSED: by default the DOM building will use characters.
+ * @param ctx  the user data (XML parser context)
+ * @param ch  a xmlChar string
+ * @param len  the number of xmlChar
  */
 typedef void (*ignorableWhitespaceSAXFunc) (void *ctx,
 				const xmlChar *ch,
 				int len);
 /**
- * processingInstructionSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @target:  the target name
- * @data: the PI data's
+ * SAX callback for processing instructions.
  *
- * A processing instruction has been parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param target  the target name
+ * @param data  the PI data's
  */
 typedef void (*processingInstructionSAXFunc) (void *ctx,
 				const xmlChar *target,
 				const xmlChar *data);
 /**
- * commentSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @value:  the comment content
+ * SAX callback for comments.
  *
- * A comment has been parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param value  the comment content
  */
 typedef void (*commentSAXFunc) (void *ctx,
 				const xmlChar *value);
 /**
- * cdataBlockSAXFunc:
- * @ctx:  the user data (XML parser context)
- * @value:  The pcdata content
- * @len:  the block length
+ * SAX callback for CDATA sections.
  *
- * Called when a pcdata block has been parsed.
+ * @param ctx  the user data (XML parser context)
+ * @param value  The pcdata content
+ * @param len  the block length
  */
 typedef void (*cdataBlockSAXFunc) (
 	                        void *ctx,
 				const xmlChar *value,
 				int len);
 /**
- * warningSAXFunc:
- * @ctx:  an XML parser context
- * @msg:  the message to display/transmit
- * @...:  extra parameters for the message display
+ * SAX callback for warning messages.
  *
- * Display and format a warning messages, callback.
+ * @param ctx  an XML parser context
+ * @param msg  the message to display/transmit
+ * @param ...  extra parameters for the message display
  */
 typedef void (*warningSAXFunc) (void *ctx,
 				const char *msg, ...) LIBXML_ATTR_FORMAT(2,3);
 /**
- * errorSAXFunc:
- * @ctx:  an XML parser context
- * @msg:  the message to display/transmit
- * @...:  extra parameters for the message display
+ * SAX callback for error messages.
  *
- * Display and format an error messages, callback.
+ * @param ctx  an XML parser context
+ * @param msg  the message to display/transmit
+ * @param ...  extra parameters for the message display
  */
 typedef void (*errorSAXFunc) (void *ctx,
 				const char *msg, ...) LIBXML_ATTR_FORMAT(2,3);
 /**
- * fatalErrorSAXFunc:
- * @ctx:  an XML parser context
- * @msg:  the message to display/transmit
- * @...:  extra parameters for the message display
+ * SAX callback for fatal error messages.
  *
- * Display and format fatal error messages, callback.
- * Note: so far fatalError() SAX callbacks are not used, error()
- *       get all the callbacks for errors.
+ * @param ctx  an XML parser context
+ * @param msg  the message to display/transmit
+ * @param ...  extra parameters for the message display
  */
 typedef void (*fatalErrorSAXFunc) (void *ctx,
 				const char *msg, ...) LIBXML_ATTR_FORMAT(2,3);
 /**
- * isStandaloneSAXFunc:
- * @ctx:  the user data (XML parser context)
+ * SAX callback to get standalone status.
  *
- * Is this document tagged standalone?
- *
- * Returns 1 if true
+ * @param ctx  the user data (XML parser context)
+ * @returns 1 if true
  */
 typedef int (*isStandaloneSAXFunc) (void *ctx);
 /**
- * hasInternalSubsetSAXFunc:
- * @ctx:  the user data (XML parser context)
- *
- * Does this document has an internal subset.
+ * SAX callback to get internal subset status.
  *
- * Returns 1 if true
+ * @param ctx  the user data (XML parser context)
+ * @returns 1 if true
  */
 typedef int (*hasInternalSubsetSAXFunc) (void *ctx);
 
 /**
- * hasExternalSubsetSAXFunc:
- * @ctx:  the user data (XML parser context)
- *
- * Does this document has an external subset?
+ * SAX callback to get external subset status.
  *
- * Returns 1 if true
+ * @param ctx  the user data (XML parser context)
+ * @returns 1 if true
  */
 typedef int (*hasExternalSubsetSAXFunc) (void *ctx);
 
@@ -836,29 +948,27 @@ typedef int (*hasExternalSubsetSAXFunc) (void *ctx);
  *									*
  ************************************************************************/
 /**
- * XML_SAX2_MAGIC:
- *
- * Special constant found in SAX2 blocks initialized fields
+ * Special constant required for SAX2 handlers.
  */
 #define XML_SAX2_MAGIC 0xDEEDBEAF
 
 /**
- * startElementNsSAX2Func:
- * @ctx:  the user data (XML parser context)
- * @localname:  the local name of the element
- * @prefix:  the element namespace prefix if available
- * @URI:  the element namespace name if available
- * @nb_namespaces:  number of namespace definitions on that node
- * @namespaces:  pointer to the array of prefix/URI pairs namespace definitions
- * @nb_attributes:  the number of attributes on that node
- * @nb_defaulted:  the number of defaulted attributes. The defaulted
- *                  ones are at the end of the array
- * @attributes:  pointer to the array of (localname/prefix/URI/value/end)
- *               attribute values.
+ * SAX2 callback for start tags.
  *
- * SAX2 callback when an element start has been detected by the parser.
  * It provides the namespace information for the element, as well as
  * the new namespace declarations on the element.
+ *
+ * @param ctx  the user data (XML parser context)
+ * @param localname  the local name of the element
+ * @param prefix  the element namespace prefix if available
+ * @param URI  the element namespace name if available
+ * @param nb_namespaces  number of namespace definitions on that node
+ * @param namespaces  pointer to the array of prefix/URI pairs namespace definitions
+ * @param nb_attributes  the number of attributes on that node
+ * @param nb_defaulted  the number of defaulted attributes. The defaulted
+ *                  ones are at the end of the array
+ * @param attributes  pointer to the array of (localname/prefix/URI/value/end)
+ *               attribute values.
  */
 
 typedef void (*startElementNsSAX2Func) (void *ctx,
@@ -872,14 +982,14 @@ typedef void (*startElementNsSAX2Func) (void *ctx,
 					const xmlChar **attributes);
 
 /**
- * endElementNsSAX2Func:
- * @ctx:  the user data (XML parser context)
- * @localname:  the local name of the element
- * @prefix:  the element namespace prefix if available
- * @URI:  the element namespace name if available
+ * SAX2 callback for end tags.
  *
- * SAX2 callback when an element end has been detected by the parser.
  * It provides the namespace information for the element.
+ *
+ * @param ctx  the user data (XML parser context)
+ * @param localname  the local name of the element
+ * @param prefix  the element namespace prefix if available
+ * @param URI  the element namespace name if available
  */
 
 typedef void (*endElementNsSAX2Func)   (void *ctx,
@@ -887,28 +997,101 @@ typedef void (*endElementNsSAX2Func)   (void *ctx,
 					const xmlChar *prefix,
 					const xmlChar *URI);
 
-
+/**
+ * Callbacks for SAX parser
+ *
+ * For DTD-related handlers, it's recommended to either use the
+ * original libxml2 handler or set them to NULL if DTDs can be
+ * ignored.
+ */
 struct _xmlSAXHandler {
-    /*
-     * For DTD-related handlers, it's recommended to either use the
-     * original libxml2 handler or set them to NULL if DTDs can be
-     * ignored.
-     */
-    internalSubsetSAXFunc internalSubset; /* DTD */
-    isStandaloneSAXFunc isStandalone; /* unused */
-    hasInternalSubsetSAXFunc hasInternalSubset; /* DTD */
-    hasExternalSubsetSAXFunc hasExternalSubset; /* DTD */
-    resolveEntitySAXFunc resolveEntity; /* DTD */
-    getEntitySAXFunc getEntity; /* DTD */
-    entityDeclSAXFunc entityDecl; /* DTD */
-    notationDeclSAXFunc notationDecl; /* DTD */
-    attributeDeclSAXFunc attributeDecl; /* DTD */
-    elementDeclSAXFunc elementDecl; /* DTD */
-    unparsedEntityDeclSAXFunc unparsedEntityDecl; /* DTD */
-    setDocumentLocatorSAXFunc setDocumentLocator; /* deprecated */
+    /**
+     * Called after the start of the document type declaration
+     * was parsed.
+     *
+     * Should typically not be modified.
+     */
+    internalSubsetSAXFunc internalSubset;
+    /**
+     * Standalone status. Not invoked by the parser. Not supposed
+     * to be changed by applications.
+     */
+    isStandaloneSAXFunc isStandalone;
+    /**
+     * Internal subset availability. Not invoked by the parser.
+     * Not supposed to be changed by applications.
+     */
+    hasInternalSubsetSAXFunc hasInternalSubset;
+    /**
+     * External subset availability. Not invoked by the parser.
+     * Not supposed to be changed by applications.
+     */
+    hasExternalSubsetSAXFunc hasExternalSubset;
+    /**
+     * Only called when loading external DTDs. Not called to load
+     * external entities.
+     *
+     * Should typically not be modified.
+     */
+    resolveEntitySAXFunc resolveEntity;
+    /**
+     * Called when looking up general entities.
+     *
+     * Should typically not be modified.
+     */
+    getEntitySAXFunc getEntity;
+    /**
+     * Called after an entity declaration was parsed.
+     *
+     * Should typically not be modified.
+     */
+    entityDeclSAXFunc entityDecl;
+    /**
+     * Called after a notation declaration was parsed.
+     *
+     * Should typically not be modified.
+     */
+    notationDeclSAXFunc notationDecl;
+    /**
+     * Called after an attribute declaration was parsed.
+     *
+     * Should typically not be modified.
+     */
+    attributeDeclSAXFunc attributeDecl;
+    /**
+     * Called after an element declaration was parsed.
+     *
+     * Should typically not be modified.
+     */
+    elementDeclSAXFunc elementDecl;
+    /**
+     * Called after an unparsed entity declaration was parsed.
+     *
+     * Should typically not be modified.
+     */
+    unparsedEntityDeclSAXFunc unparsedEntityDecl;
+    /**
+     * This callback receives the "document locator" at startup,
+     * which is always the global xmlDefaultSAXLocator.
+     *
+     * Everything is available on the context, so this is useless in
+     * our case.
+     */
+    setDocumentLocatorSAXFunc setDocumentLocator;
+    /**
+     * Called after the XML declaration was parsed.
+     *
+     * Use xmlCtxtGetVersion(), xmlCtxtGetDeclaredEncoding() and
+     * xmlCtxtGetStandalone() to get data from the XML declaration.
+     */
     startDocumentSAXFunc startDocument;
+    /**
+     * Called at the end of the document.
+     */
     endDocumentSAXFunc endDocument;
-    /*
+    /**
+     * Legacy start tag handler
+     *
      * `startElement` and `endElement` are only used by the legacy SAX1
      * interface and should not be used in new software. If you really
      * have to enable SAX1, the preferred way is set the `initialized`
@@ -922,46 +1105,102 @@ struct _xmlSAXHandler {
      * together with custom SAX callbacks.
      */
     startElementSAXFunc startElement;
+    /**
+     * See _xmlSAXHandler.startElement
+     */
     endElementSAXFunc endElement;
+    /**
+     * Called after an entity reference was parsed.
+     */
     referenceSAXFunc reference;
+    /**
+     * Called after a character data was parsed.
+     */
     charactersSAXFunc characters;
-    /*
+    /**
+     * Called after "ignorable" whitespace was parsed.
+     *
      * `ignorableWhitespace` should always be set to the same value
      * as `characters`. Otherwise, the parser will try to detect
      * whitespace which is unreliable.
      */
     ignorableWhitespaceSAXFunc ignorableWhitespace;
+    /**
+     * Called after a processing instruction was parsed.
+     */
     processingInstructionSAXFunc processingInstruction;
+    /**
+     * Called after a comment was parsed.
+     */
     commentSAXFunc comment;
+    /**
+     * Callback for warning messages.
+     */
     warningSAXFunc warning;
+    /**
+     * Callback for error messages.
+     */
     errorSAXFunc error;
-    fatalErrorSAXFunc fatalError; /* unused, `error` gets all the errors */
-    getParameterEntitySAXFunc getParameterEntity; /* DTD */
+    /**
+     * Unused, all errors go to `error`.
+     */
+    fatalErrorSAXFunc fatalError;
+    /**
+     * Called when looking up parameter entities.
+     *
+     * Should typically not be modified.
+     */
+    getParameterEntitySAXFunc getParameterEntity;
+    /**
+     * Called after a CDATA section was parsed.
+     */
     cdataBlockSAXFunc cdataBlock;
-    externalSubsetSAXFunc externalSubset; /* DTD */
-    /*
-     * `initialized` should always be set to XML_SAX2_MAGIC to enable the
-     * modern SAX2 interface.
+    /**
+     * Called to parse the external subset.
+     *
+     * Should typically not be modified.
+     */
+    externalSubsetSAXFunc externalSubset;
+    /**
+     * Legacy magic value
+     *
+     * `initialized` should always be set to XML_SAX2_MAGIC to
+     * enable the modern SAX2 interface.
      */
     unsigned int initialized;
-    /*
-     * The following members are only used by the SAX2 interface.
+    /**
+     * Application data
      */
     void *_private;
+    /**
+     * Called after a start tag was parsed.
+     */
     startElementNsSAX2Func startElementNs;
+    /**
+     * Called after an end tag was parsed.
+     */
     endElementNsSAX2Func endElementNs;
-    /*
+    /**
+     * Structured error handler.
+     *
      * Takes precedence over `error` or `warning`, but modern code
-     * should use xmlCtxtSetErrorHandler.
+     * should use xmlCtxtSetErrorHandler().
      */
     xmlStructuredErrorFunc serror;
 };
 
-/*
- * SAX Version 1
+/**
+ * SAX handler, version 1.
+ *
+ * @deprecated Use version 2 handlers.
  */
 typedef struct _xmlSAXHandlerV1 xmlSAXHandlerV1;
 typedef xmlSAXHandlerV1 *xmlSAXHandlerV1Ptr;
+/**
+ * SAX handler, version 1.
+ *
+ * @deprecated Use version 2 handlers.
+ */
 struct _xmlSAXHandlerV1 {
     internalSubsetSAXFunc internalSubset;
     isStandaloneSAXFunc isStandalone;
@@ -995,18 +1234,19 @@ struct _xmlSAXHandlerV1 {
 
 
 /**
- * xmlExternalEntityLoader:
- * @URL: The System ID of the resource requested
- * @ID: The Public ID of the resource requested
- * @context: the XML parser context
+ * Callback for external entity loader.
  *
- * External entity loaders types.
+ * The URL is not resolved using XML catalogs before being passed
+ * to the callback.
  *
- * Returns the entity input parser.
+ * @param URL  The URL or system ID of the resource requested
+ * @param publicId  The public ID of the resource requested (optional)
+ * @param context  the XML parser context
+ * @returns the entity input parser or NULL on error.
  */
-typedef xmlParserInputPtr (*xmlExternalEntityLoader) (const char *URL,
-					 const char *ID,
-					 xmlParserCtxtPtr context);
+typedef xmlParserInput *(*xmlExternalEntityLoader) (const char *URL,
+					 const char *publicId,
+					 xmlParserCtxt *context);
 
 /*
  * Variables
@@ -1014,10 +1254,14 @@ typedef xmlParserInputPtr (*xmlExternalEntityLoader) (const char *URL,
 
 XMLPUBVAR const char *const xmlParserVersion;
 
-/** DOC_DISABLE */
+/** @cond ignore */
+
 XML_DEPRECATED
 XMLPUBVAR const xmlSAXLocator xmlDefaultSAXLocator;
 #ifdef LIBXML_SAX1_ENABLED
+/**
+ * @deprecated Use #xmlSAXVersion or #xmlSAX2InitDefaultSAXHandler
+ */
 XML_DEPRECATED
 XMLPUBVAR const xmlSAXHandlerV1 xmlDefaultSAXHandler;
 #endif
@@ -1038,31 +1282,96 @@ XML_DEPRECATED
 XMLPUBFUN int *__xmlSubstituteEntitiesDefaultValue(void);
 
 #ifdef LIBXML_OUTPUT_ENABLED
+XML_DEPRECATED
 XMLPUBFUN int *__xmlIndentTreeOutput(void);
+XML_DEPRECATED
 XMLPUBFUN const char **__xmlTreeIndentString(void);
+XML_DEPRECATED
 XMLPUBFUN int *__xmlSaveNoEmptyTags(void);
 #endif
 
+/** @endcond */
+
 #ifndef XML_GLOBALS_NO_REDEFINITION
+  /**
+   * Thread-local setting to enable validation. Defaults to 0.
+   *
+   * @deprecated Use the parser option XML_PARSE_DTDVALID.
+   */
   #define xmlDoValidityCheckingDefaultValue \
     (*__xmlDoValidityCheckingDefaultValue())
+  /**
+   * Thread-local setting to disable warnings. Defaults to 1.
+   *
+   * @deprecated Use the parser option XML_PARSE_NOWARNING.
+   */
   #define xmlGetWarningsDefaultValue \
     (*__xmlGetWarningsDefaultValue())
+  /**
+   * Thread-local setting to ignore some whitespace. Defaults
+   * to 1.
+   *
+   * @deprecated Use the parser option XML_PARSE_NOBLANKS.
+   */
   #define xmlKeepBlanksDefaultValue (*__xmlKeepBlanksDefaultValue())
+  /**
+   * Thread-local setting to store line numbers. Defaults
+   * to 0, but is always enabled after setting parser options.
+   *
+   * @deprecated Shouldn't be needed when using parser options.
+   */
   #define xmlLineNumbersDefaultValue \
     (*__xmlLineNumbersDefaultValue())
+  /**
+   * Thread-local setting to enable loading of external DTDs.
+   * Defaults to 0.
+   *
+   * @deprecated Use the parser option XML_PARSE_DTDLOAD.
+   */
   #define xmlLoadExtDtdDefaultValue (*__xmlLoadExtDtdDefaultValue())
+  /**
+   * Thread-local setting to enable pedantic warnings.
+   * Defaults to 0.
+   *
+   * @deprecated Use the parser option XML_PARSE_PEDANTIC.
+   */
   #define xmlPedanticParserDefaultValue \
     (*__xmlPedanticParserDefaultValue())
+  /**
+   * Thread-local setting to enable entity substitution.
+   * Defaults to 0.
+   *
+   * @deprecated Use the parser option XML_PARSE_NOENT.
+   */
   #define xmlSubstituteEntitiesDefaultValue \
     (*__xmlSubstituteEntitiesDefaultValue())
   #ifdef LIBXML_OUTPUT_ENABLED
+    /**
+     * Thread-local setting to disable indenting when
+     * formatting output. Defaults to 1.
+     *
+     * @deprecated Use the xmlsave.h API with option
+     * XML_SAVE_NO_INDENT.
+     */
     #define xmlIndentTreeOutput (*__xmlIndentTreeOutput())
+    /**
+     * Thread-local setting to change the indent string.
+     * Defaults to two spaces.
+     *
+     * @deprecated Use the xmlsave.h API and
+     * xmlSaveSetIndentString().
+     */
     #define xmlTreeIndentString (*__xmlTreeIndentString())
+    /**
+     * Thread-local setting to disable empty tags when
+     * serializing. Defaults to 0.
+     *
+     * @deprecated Use the xmlsave.h API with option
+     * XML_SAVE_NO_EMPTY.
+     */
     #define xmlSaveNoEmptyTags (*__xmlSaveNoEmptyTags())
   #endif
 #endif
-/** DOC_ENABLE */
 
 /*
  * Init/Cleanup
@@ -1083,46 +1392,47 @@ XMLPUBFUN void
  */
 XML_DEPRECATED
 XMLPUBFUN int
-		xmlParserInputRead	(xmlParserInputPtr in,
+		xmlParserInputRead	(xmlParserInput *in,
 					 int len);
 XMLPUBFUN int
-		xmlParserInputGrow	(xmlParserInputPtr in,
+		xmlParserInputGrow	(xmlParserInput *in,
 					 int len);
 
 /*
  * Basic parsing Interfaces
  */
 #ifdef LIBXML_SAX1_ENABLED
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlParseDoc		(const xmlChar *cur);
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlParseFile		(const char *filename);
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlParseMemory		(const char *buffer,
 					 int size);
 #endif /* LIBXML_SAX1_ENABLED */
 XML_DEPRECATED
 XMLPUBFUN int
 		xmlSubstituteEntitiesDefault(int val);
-XML_DEPRECATED
-XMLPUBFUN int
-                xmlThrDefSubstituteEntitiesDefaultValue(int v);
 XMLPUBFUN int
 		xmlKeepBlanksDefault	(int val);
-XML_DEPRECATED
-XMLPUBFUN int
-		xmlThrDefKeepBlanksDefaultValue(int v);
 XMLPUBFUN void
-		xmlStopParser		(xmlParserCtxtPtr ctxt);
+		xmlStopParser		(xmlParserCtxt *ctxt);
 XML_DEPRECATED
 XMLPUBFUN int
 		xmlPedanticParserDefault(int val);
 XML_DEPRECATED
 XMLPUBFUN int
-                xmlThrDefPedanticParserDefaultValue(int v);
+		xmlLineNumbersDefault	(int val);
+
 XML_DEPRECATED
 XMLPUBFUN int
-		xmlLineNumbersDefault	(int val);
+                xmlThrDefSubstituteEntitiesDefaultValue(int v);
+XML_DEPRECATED
+XMLPUBFUN int
+		xmlThrDefKeepBlanksDefaultValue(int v);
+XML_DEPRECATED
+XMLPUBFUN int
+                xmlThrDefPedanticParserDefaultValue(int v);
 XML_DEPRECATED
 XMLPUBFUN int
                 xmlThrDefLineNumbersDefaultValue(int v);
@@ -1141,14 +1451,14 @@ XMLPUBFUN int
  * Recovery mode
  */
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlRecoverDoc		(const xmlChar *cur);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlRecoverMemory	(const char *buffer,
 					 int size);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlRecoverFile		(const char *filename);
 #endif /* LIBXML_SAX1_ENABLED */
 
@@ -1156,162 +1466,163 @@ XMLPUBFUN xmlDocPtr
  * Less common routines and SAX interfaces
  */
 XMLPUBFUN int
-		xmlParseDocument	(xmlParserCtxtPtr ctxt);
+		xmlParseDocument	(xmlParserCtxt *ctxt);
 XML_DEPRECATED
 XMLPUBFUN int
-		xmlParseExtParsedEnt	(xmlParserCtxtPtr ctxt);
+		xmlParseExtParsedEnt	(xmlParserCtxt *ctxt);
 #ifdef LIBXML_SAX1_ENABLED
 XML_DEPRECATED
 XMLPUBFUN int
-		xmlSAXUserParseFile	(xmlSAXHandlerPtr sax,
+		xmlSAXUserParseFile	(xmlSAXHandler *sax,
 					 void *user_data,
 					 const char *filename);
 XML_DEPRECATED
 XMLPUBFUN int
-		xmlSAXUserParseMemory	(xmlSAXHandlerPtr sax,
+		xmlSAXUserParseMemory	(xmlSAXHandler *sax,
 					 void *user_data,
 					 const char *buffer,
 					 int size);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
-		xmlSAXParseDoc		(xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlDoc *
+		xmlSAXParseDoc		(xmlSAXHandler *sax,
 					 const xmlChar *cur,
 					 int recovery);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
-		xmlSAXParseMemory	(xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlDoc *
+		xmlSAXParseMemory	(xmlSAXHandler *sax,
 					 const char *buffer,
 					 int size,
 					 int recovery);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
-		xmlSAXParseMemoryWithData (xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlDoc *
+		xmlSAXParseMemoryWithData (xmlSAXHandler *sax,
 					 const char *buffer,
 					 int size,
 					 int recovery,
 					 void *data);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
-		xmlSAXParseFile		(xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlDoc *
+		xmlSAXParseFile		(xmlSAXHandler *sax,
 					 const char *filename,
 					 int recovery);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
-		xmlSAXParseFileWithData	(xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlDoc *
+		xmlSAXParseFileWithData	(xmlSAXHandler *sax,
 					 const char *filename,
 					 int recovery,
 					 void *data);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
-		xmlSAXParseEntity	(xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlDoc *
+		xmlSAXParseEntity	(xmlSAXHandler *sax,
 					 const char *filename);
 XML_DEPRECATED
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlParseEntity		(const char *filename);
 #endif /* LIBXML_SAX1_ENABLED */
 
 #ifdef LIBXML_VALID_ENABLED
-XMLPUBFUN xmlDtdPtr
-		xmlCtxtParseDtd		(xmlParserCtxtPtr ctxt,
-					 xmlParserInputPtr input,
-					 const xmlChar *ExternalID,
-					 const xmlChar *SystemID);
+XMLPUBFUN xmlDtd *
+		xmlCtxtParseDtd		(xmlParserCtxt *ctxt,
+					 xmlParserInput *input,
+					 const xmlChar *publicId,
+					 const xmlChar *systemId);
 XMLPUBFUN int
-		xmlCtxtValidateDocument	(xmlParserCtxtPtr ctxt,
-					 xmlDocPtr doc);
+		xmlCtxtValidateDocument	(xmlParserCtxt *ctxt,
+					 xmlDoc *doc);
 XMLPUBFUN int
-		xmlCtxtValidateDtd	(xmlParserCtxtPtr ctxt,
-					 xmlDocPtr doc,
-					 xmlDtdPtr dtd);
+		xmlCtxtValidateDtd	(xmlParserCtxt *ctxt,
+					 xmlDoc *doc,
+					 xmlDtd *dtd);
 XML_DEPRECATED
-XMLPUBFUN xmlDtdPtr
-		xmlSAXParseDTD		(xmlSAXHandlerPtr sax,
-					 const xmlChar *ExternalID,
-					 const xmlChar *SystemID);
-XMLPUBFUN xmlDtdPtr
-		xmlParseDTD		(const xmlChar *ExternalID,
-					 const xmlChar *SystemID);
-XMLPUBFUN xmlDtdPtr
-		xmlIOParseDTD		(xmlSAXHandlerPtr sax,
-					 xmlParserInputBufferPtr input,
+XMLPUBFUN xmlDtd *
+		xmlSAXParseDTD		(xmlSAXHandler *sax,
+					 const xmlChar *publicId,
+					 const xmlChar *systemId);
+XMLPUBFUN xmlDtd *
+		xmlParseDTD		(const xmlChar *publicId,
+					 const xmlChar *systemId);
+XMLPUBFUN xmlDtd *
+		xmlIOParseDTD		(xmlSAXHandler *sax,
+					 xmlParserInputBuffer *input,
 					 xmlCharEncoding enc);
 #endif /* LIBXML_VALID_ENABLE */
 #ifdef LIBXML_SAX1_ENABLED
 XMLPUBFUN int
-		xmlParseBalancedChunkMemory(xmlDocPtr doc,
-					 xmlSAXHandlerPtr sax,
+		xmlParseBalancedChunkMemory(xmlDoc *doc,
+					 xmlSAXHandler *sax,
 					 void *user_data,
 					 int depth,
 					 const xmlChar *string,
-					 xmlNodePtr *lst);
+					 xmlNode **lst);
 #endif /* LIBXML_SAX1_ENABLED */
 XMLPUBFUN xmlParserErrors
-		xmlParseInNodeContext	(xmlNodePtr node,
+		xmlParseInNodeContext	(xmlNode *node,
 					 const char *data,
 					 int datalen,
 					 int options,
-					 xmlNodePtr *lst);
+					 xmlNode **lst);
 #ifdef LIBXML_SAX1_ENABLED
 XMLPUBFUN int
-		xmlParseBalancedChunkMemoryRecover(xmlDocPtr doc,
-                     xmlSAXHandlerPtr sax,
+		xmlParseBalancedChunkMemoryRecover(xmlDoc *doc,
+                     xmlSAXHandler *sax,
                      void *user_data,
                      int depth,
                      const xmlChar *string,
-                     xmlNodePtr *lst,
+                     xmlNode **lst,
                      int recover);
 XML_DEPRECATED
 XMLPUBFUN int
-		xmlParseExternalEntity	(xmlDocPtr doc,
-					 xmlSAXHandlerPtr sax,
+		xmlParseExternalEntity	(xmlDoc *doc,
+					 xmlSAXHandler *sax,
 					 void *user_data,
 					 int depth,
 					 const xmlChar *URL,
 					 const xmlChar *ID,
-					 xmlNodePtr *lst);
+					 xmlNode **lst);
 #endif /* LIBXML_SAX1_ENABLED */
 XMLPUBFUN int
-		xmlParseCtxtExternalEntity(xmlParserCtxtPtr ctx,
+		xmlParseCtxtExternalEntity(xmlParserCtxt *ctx,
 					 const xmlChar *URL,
 					 const xmlChar *ID,
-					 xmlNodePtr *lst);
+					 xmlNode **lst);
 
 /*
  * Parser contexts handling.
  */
-XMLPUBFUN xmlParserCtxtPtr
+XMLPUBFUN xmlParserCtxt *
 		xmlNewParserCtxt	(void);
-XMLPUBFUN xmlParserCtxtPtr
+XMLPUBFUN xmlParserCtxt *
 		xmlNewSAXParserCtxt	(const xmlSAXHandler *sax,
 					 void *userData);
 XMLPUBFUN int
-		xmlInitParserCtxt	(xmlParserCtxtPtr ctxt);
+		xmlInitParserCtxt	(xmlParserCtxt *ctxt);
+XML_DEPRECATED
 XMLPUBFUN void
-		xmlClearParserCtxt	(xmlParserCtxtPtr ctxt);
+		xmlClearParserCtxt	(xmlParserCtxt *ctxt);
 XMLPUBFUN void
-		xmlFreeParserCtxt	(xmlParserCtxtPtr ctxt);
+		xmlFreeParserCtxt	(xmlParserCtxt *ctxt);
 #ifdef LIBXML_SAX1_ENABLED
 XML_DEPRECATED
 XMLPUBFUN void
-		xmlSetupParserForBuffer	(xmlParserCtxtPtr ctxt,
+		xmlSetupParserForBuffer	(xmlParserCtxt *ctxt,
 					 const xmlChar* buffer,
 					 const char *filename);
 #endif /* LIBXML_SAX1_ENABLED */
-XMLPUBFUN xmlParserCtxtPtr
+XMLPUBFUN xmlParserCtxt *
 		xmlCreateDocParserCtxt	(const xmlChar *cur);
 
 #ifdef LIBXML_PUSH_ENABLED
 /*
  * Interfaces for the Push mode.
  */
-XMLPUBFUN xmlParserCtxtPtr
-		xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlParserCtxt *
+		xmlCreatePushParserCtxt(xmlSAXHandler *sax,
 					 void *user_data,
 					 const char *chunk,
 					 int size,
 					 const char *filename);
 XMLPUBFUN int
-		xmlParseChunk		(xmlParserCtxtPtr ctxt,
+		xmlParseChunk		(xmlParserCtxt *ctxt,
 					 const char *chunk,
 					 int size,
 					 int terminate);
@@ -1321,17 +1632,17 @@ XMLPUBFUN int
  * Special I/O mode.
  */
 
-XMLPUBFUN xmlParserCtxtPtr
-		xmlCreateIOParserCtxt	(xmlSAXHandlerPtr sax,
+XMLPUBFUN xmlParserCtxt *
+		xmlCreateIOParserCtxt	(xmlSAXHandler *sax,
 					 void *user_data,
 					 xmlInputReadCallback   ioread,
 					 xmlInputCloseCallback  ioclose,
 					 void *ioctx,
 					 xmlCharEncoding enc);
 
-XMLPUBFUN xmlParserInputPtr
-		xmlNewIOInputStream	(xmlParserCtxtPtr ctxt,
-					 xmlParserInputBufferPtr input,
+XMLPUBFUN xmlParserInput *
+		xmlNewIOInputStream	(xmlParserCtxt *ctxt,
+					 xmlParserInputBuffer *input,
 					 xmlCharEncoding enc);
 
 /*
@@ -1339,22 +1650,22 @@ XMLPUBFUN xmlParserInputPtr
  */
 XML_DEPRECATED
 XMLPUBFUN const xmlParserNodeInfo*
-		xmlParserFindNodeInfo	(xmlParserCtxtPtr ctxt,
-				         xmlNodePtr node);
+		xmlParserFindNodeInfo	(xmlParserCtxt *ctxt,
+				         xmlNode *node);
 XML_DEPRECATED
 XMLPUBFUN void
-		xmlInitNodeInfoSeq	(xmlParserNodeInfoSeqPtr seq);
+		xmlInitNodeInfoSeq	(xmlParserNodeInfoSeq *seq);
 XML_DEPRECATED
 XMLPUBFUN void
-		xmlClearNodeInfoSeq	(xmlParserNodeInfoSeqPtr seq);
+		xmlClearNodeInfoSeq	(xmlParserNodeInfoSeq *seq);
 XML_DEPRECATED
 XMLPUBFUN unsigned long
-		xmlParserFindNodeInfoIndex(xmlParserNodeInfoSeqPtr seq,
-                                         xmlNodePtr node);
+		xmlParserFindNodeInfoIndex(xmlParserNodeInfoSeq *seq,
+                                         xmlNode *node);
 XML_DEPRECATED
 XMLPUBFUN void
-		xmlParserAddNodeInfo	(xmlParserCtxtPtr ctxt,
-					 xmlParserNodeInfoPtr info);
+		xmlParserAddNodeInfo	(xmlParserCtxt *ctxt,
+					 xmlParserNodeInfo *info);
 
 /*
  * External entities handling actually implemented in xmlIO.
@@ -1364,188 +1675,372 @@ XMLPUBFUN void
 		xmlSetExternalEntityLoader(xmlExternalEntityLoader f);
 XMLPUBFUN xmlExternalEntityLoader
 		xmlGetExternalEntityLoader(void);
-XMLPUBFUN xmlParserInputPtr
+XMLPUBFUN xmlParserInput *
 		xmlLoadExternalEntity	(const char *URL,
 					 const char *ID,
-					 xmlParserCtxtPtr ctxt);
+					 xmlParserCtxt *ctxt);
 
 XML_DEPRECATED
 XMLPUBFUN long
-		xmlByteConsumed		(xmlParserCtxtPtr ctxt);
+		xmlByteConsumed		(xmlParserCtxt *ctxt);
 
 /*
  * New set of simpler/more flexible APIs
  */
+
 /**
- * xmlParserOption:
- *
- * This is the set of XML parser options that can be passed down
- * to the xmlReadDoc() and similar calls.
+ * This is the set of XML parser options that can be passed to
+ * #xmlReadDoc, #xmlCtxtSetOptions and other functions.
  */
 typedef enum {
-    XML_PARSE_RECOVER	= 1<<0,	/* recover on errors */
-    XML_PARSE_NOENT	= 1<<1,	/* substitute entities */
-    XML_PARSE_DTDLOAD	= 1<<2,	/* load the external subset */
-    XML_PARSE_DTDATTR	= 1<<3,	/* default DTD attributes */
-    XML_PARSE_DTDVALID	= 1<<4,	/* validate with the DTD */
-    XML_PARSE_NOERROR	= 1<<5,	/* suppress error reports */
-    XML_PARSE_NOWARNING	= 1<<6,	/* suppress warning reports */
-    XML_PARSE_PEDANTIC	= 1<<7,	/* pedantic error reporting */
-    XML_PARSE_NOBLANKS	= 1<<8,	/* remove blank nodes */
-    XML_PARSE_SAX1	= 1<<9,	/* use the SAX1 interface internally */
-    XML_PARSE_XINCLUDE	= 1<<10,/* Implement XInclude substitution  */
-    XML_PARSE_NONET	= 1<<11,/* Forbid network access */
-    XML_PARSE_NODICT	= 1<<12,/* Do not reuse the context dictionary */
-    XML_PARSE_NSCLEAN	= 1<<13,/* remove redundant namespaces declarations */
-    XML_PARSE_NOCDATA	= 1<<14,/* merge CDATA as text nodes */
-    XML_PARSE_NOXINCNODE= 1<<15,/* do not generate XINCLUDE START/END nodes */
-    XML_PARSE_COMPACT   = 1<<16,/* compact small text nodes; no modification of
-                                   the tree allowed afterwards (will possibly
-				   crash if you try to modify the tree) */
-    XML_PARSE_OLD10	= 1<<17,/* parse using XML-1.0 before update 5 */
-    XML_PARSE_NOBASEFIX = 1<<18,/* do not fixup XINCLUDE xml:base uris */
-    XML_PARSE_HUGE      = 1<<19,/* relax any hardcoded limit from the parser */
-    XML_PARSE_OLDSAX    = 1<<20,/* parse using SAX2 interface before 2.7.0 */
-    XML_PARSE_IGNORE_ENC= 1<<21,/* ignore internal document encoding hint */
-    XML_PARSE_BIG_LINES = 1<<22,/* Store big lines numbers in text PSVI field */
-    /* since 2.13.0 */
-    XML_PARSE_NO_XXE    = 1<<23,/* disable loading of external content */
-    /* since 2.14.0 */
-    XML_PARSE_UNZIP          = 1<<24,/* allow compressed content */
-    XML_PARSE_NO_SYS_CATALOG = 1<<25,/* disable global system catalog */
-    XML_PARSE_CATALOG_PI     = 1<<26 /* allow catalog PIs */
+    /**
+     * Enable "recovery" mode which allows non-wellformed documents.
+     * How this mode behaves exactly is unspecified and may change
+     * without further notice. Use of this feature is DISCOURAGED.
+     *
+     * Not supported by the push parser.
+     */
+    XML_PARSE_RECOVER = 1<<0,
+    /**
+     * Despite the confusing name, this option enables substitution
+     * of entities. The resulting tree won't contain any entity
+     * reference nodes.
+     *
+     * This option also enables loading of external entities (both
+     * general and parameter entities) which is dangerous. If you
+     * process untrusted data, it's recommended to set the
+     * XML_PARSE_NO_XXE option to disable loading of external
+     * entities.
+     */
+    XML_PARSE_NOENT = 1<<1,
+    /**
+     * Enables loading of an external DTD and the loading and
+     * substitution of external parameter entities. Has no effect
+     * if XML_PARSE_NO_XXE is set.
+     */
+    XML_PARSE_DTDLOAD = 1<<2,
+    /**
+     * Adds default attributes from the DTD to the result document.
+     *
+     * Implies XML_PARSE_DTDLOAD, but loading of external content
+     * can be disabled with XML_PARSE_NO_XXE.
+     */
+    XML_PARSE_DTDATTR = 1<<3,
+    /**
+     * This option enables DTD validation which requires to load
+     * external DTDs and external entities (both general and
+     * parameter entities) unless XML_PARSE_NO_XXE was set.
+     *
+     * DTD validation is vulnerable to algorithmic complexity
+     * attacks and should never be enabled with untrusted input.
+     */
+    XML_PARSE_DTDVALID = 1<<4,
+    /**
+     * Disable error and warning reports to the error handlers.
+     * Errors are still accessible with xmlCtxtGetLastError().
+     */
+    XML_PARSE_NOERROR = 1<<5,
+    /**
+     * Disable warning reports.
+     */
+    XML_PARSE_NOWARNING = 1<<6,
+    /**
+     * Enable some pedantic warnings.
+     */
+    XML_PARSE_PEDANTIC = 1<<7,
+    /**
+     * Remove some whitespace from the result document. Where to
+     * remove whitespace depends on DTD element declarations or a
+     * broken heuristic with unfixable bugs. Use of this option is
+     * DISCOURAGED.
+     *
+     * Not supported by the push parser.
+     */
+    XML_PARSE_NOBLANKS = 1<<8,
+    /**
+     * Always invoke the deprecated SAX1 startElement and endElement
+     * handlers.
+     *
+     * @deprecated This option will be removed in a future version.
+     */
+    XML_PARSE_SAX1 = 1<<9,
+    /**
+     * Enable XInclude processing. This option only affects the
+     * xmlTextReader and XInclude interfaces.
+     */
+    XML_PARSE_XINCLUDE = 1<<10,
+    /**
+     * Disable network access with the built-in HTTP or FTP clients.
+     *
+     * After the last built-in network client was removed in 2.15,
+     * this option has no effect expect for being passed on to custom
+     * resource loaders.
+     */
+    XML_PARSE_NONET = 1<<11,
+    /**
+     * Create a document without interned strings, making all
+     * strings separate memory allocations.
+     */
+    XML_PARSE_NODICT = 1<<12,
+    /**
+     * Remove redundant namespace declarations from the result
+     * document.
+     */
+    XML_PARSE_NSCLEAN = 1<<13,
+    /**
+     * Output normal text nodes instead of CDATA nodes.
+     */
+    XML_PARSE_NOCDATA = 1<<14,
+    /**
+     * Don't generate XInclude start/end nodes when expanding
+     * inclusions. This option only affects the xmlTextReader
+     * and XInclude interfaces.
+     */
+    XML_PARSE_NOXINCNODE = 1<<15,
+    /**
+     * Store small strings directly in the node struct to save
+     * memory.
+     */
+    XML_PARSE_COMPACT = 1<<16,
+    /**
+     * Use old Name productions from before XML 1.0 Fifth Edition.
+     *
+     * @deprecated This option will be removed in a future version.
+     */
+    XML_PARSE_OLD10 = 1<<17,
+    /**
+     * Don't fix up XInclude xml:base URIs. This option only affects
+     * the xmlTextReader and XInclude interfaces.
+     */
+    XML_PARSE_NOBASEFIX = 1<<18,
+    /**
+     * Relax some internal limits.
+     *
+     * Maximum size of text nodes, tags, comments, processing instructions,
+     * CDATA sections, entity values
+     *
+     * normal: 10M
+     * huge:    1B
+     *
+     * Maximum size of names, system literals, pubid literals
+     *
+     * normal: 50K
+     * huge:   10M
+     *
+     * Maximum nesting depth of elements
+     *
+     * normal:  256
+     * huge:   2048
+     *
+     * Maximum nesting depth of entities
+     *
+     * normal: 20
+     * huge:   40
+     */
+    XML_PARSE_HUGE = 1<<19,
+    /**
+     * Enable an unspecified legacy mode for SAX parsers.
+     *
+     * @deprecated This option will be removed in a future version.
+     */
+    XML_PARSE_OLDSAX = 1<<20,
+    /**
+     * Ignore the encoding in the XML declaration. This option is
+     * mostly unneeded these days. The only effect is to enforce
+     * UTF-8 decoding of ASCII-like data.
+     */
+    XML_PARSE_IGNORE_ENC = 1<<21,
+    /**
+     * Enable reporting of line numbers larger than 65535.
+     */
+    XML_PARSE_BIG_LINES = 1<<22,
+    /**
+     * Disables loading of external DTDs or entities.
+     *
+     * @since 2.13.0
+     */
+    XML_PARSE_NO_XXE = 1<<23,
+    /**
+     * Enable input decompression. Setting this option is discouraged
+     * to avoid zip bombs.
+     *
+     * @since 2.14.0
+     */
+    XML_PARSE_UNZIP = 1<<24,
+    /**
+     * Disables the global system XML catalog.
+     *
+     * @since 2.14.0
+     */
+    XML_PARSE_NO_SYS_CATALOG = 1<<25,
+    /**
+     * Enable XML catalog processing instructions.
+     *
+     * @since 2.14.0
+     */
+    XML_PARSE_CATALOG_PI = 1<<26,
+    /**
+     * Force the parser to ignore IDs.
+     *
+     * @since 2.15.0
+     */
+    XML_PARSE_SKIP_IDS = 1<<27
 } xmlParserOption;
 
 XMLPUBFUN void
-		xmlCtxtReset		(xmlParserCtxtPtr ctxt);
+		xmlCtxtReset		(xmlParserCtxt *ctxt);
 XMLPUBFUN int
-		xmlCtxtResetPush	(xmlParserCtxtPtr ctxt,
+		xmlCtxtResetPush	(xmlParserCtxt *ctxt,
 					 const char *chunk,
 					 int size,
 					 const char *filename,
 					 const char *encoding);
 XMLPUBFUN int
-		xmlCtxtGetOptions	(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetOptions	(xmlParserCtxt *ctxt);
 XMLPUBFUN int
-		xmlCtxtSetOptions	(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetOptions	(xmlParserCtxt *ctxt,
 					 int options);
 XMLPUBFUN int
-		xmlCtxtUseOptions	(xmlParserCtxtPtr ctxt,
+		xmlCtxtUseOptions	(xmlParserCtxt *ctxt,
 					 int options);
 XMLPUBFUN void *
-		xmlCtxtGetPrivate	(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetPrivate	(xmlParserCtxt *ctxt);
 XMLPUBFUN void
-		xmlCtxtSetPrivate	(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetPrivate	(xmlParserCtxt *ctxt,
 					 void *priv);
 XMLPUBFUN void *
-		xmlCtxtGetCatalogs	(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetCatalogs	(xmlParserCtxt *ctxt);
 XMLPUBFUN void
-		xmlCtxtSetCatalogs	(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetCatalogs	(xmlParserCtxt *ctxt,
 					 void *catalogs);
-XMLPUBFUN xmlDictPtr
-		xmlCtxtGetDict		(xmlParserCtxtPtr ctxt);
+XMLPUBFUN xmlDict *
+		xmlCtxtGetDict		(xmlParserCtxt *ctxt);
 XMLPUBFUN void
-		xmlCtxtSetDict		(xmlParserCtxtPtr ctxt,
-					 xmlDictPtr);
+		xmlCtxtSetDict		(xmlParserCtxt *ctxt,
+					 xmlDict *);
 XMLPUBFUN xmlSAXHandler *
-		xmlCtxtGetSaxHandler	(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetSaxHandler	(xmlParserCtxt *ctxt);
 XMLPUBFUN int
-		xmlCtxtSetSaxHandler	(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetSaxHandler	(xmlParserCtxt *ctxt,
 					 const xmlSAXHandler *sax);
-XMLPUBFUN xmlDocPtr
-		xmlCtxtGetDocument	(xmlParserCtxtPtr ctxt);
+XMLPUBFUN xmlDoc *
+		xmlCtxtGetDocument	(xmlParserCtxt *ctxt);
 XMLPUBFUN int
-		xmlCtxtIsHtml		(xmlParserCtxtPtr ctxt);
+		xmlCtxtIsHtml		(xmlParserCtxt *ctxt);
 XMLPUBFUN int
-		xmlCtxtIsStopped	(xmlParserCtxtPtr ctxt);
+		xmlCtxtIsStopped	(xmlParserCtxt *ctxt);
+XMLPUBFUN int
+		xmlCtxtIsInSubset	(xmlParserCtxt *ctxt);
 #ifdef LIBXML_VALID_ENABLED
-XMLPUBFUN xmlValidCtxtPtr
-		xmlCtxtGetValidCtxt	(xmlParserCtxtPtr ctxt);
+XMLPUBFUN xmlValidCtxt *
+		xmlCtxtGetValidCtxt	(xmlParserCtxt *ctxt);
 #endif
 XMLPUBFUN const xmlChar *
-		xmlCtxtGetVersion	(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetVersion	(xmlParserCtxt *ctxt);
 XMLPUBFUN const xmlChar *
-		xmlCtxtGetDeclaredEncoding(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetDeclaredEncoding(xmlParserCtxt *ctxt);
 XMLPUBFUN int
-		xmlCtxtGetStandalone	(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetStandalone	(xmlParserCtxt *ctxt);
 XMLPUBFUN xmlParserStatus
-		xmlCtxtGetStatus	(xmlParserCtxtPtr ctxt);
+		xmlCtxtGetStatus	(xmlParserCtxt *ctxt);
+XMLPUBFUN void *
+		xmlCtxtGetUserData	(xmlParserCtxt *ctxt);
+XMLPUBFUN xmlNode *
+		xmlCtxtGetNode		(xmlParserCtxt *ctxt);
+XMLPUBFUN int
+		xmlCtxtGetDocTypeDecl	(xmlParserCtxt *ctxt,
+					 const xmlChar **name,
+					 const xmlChar **systemId,
+					 const xmlChar **publicId);
+XMLPUBFUN int
+		xmlCtxtGetInputPosition	(xmlParserCtxt *ctxt,
+					 int inputIndex,
+					 const char **filname,
+					 int *line,
+					 int *col,
+					 unsigned long *bytePos);
+XMLPUBFUN int
+		xmlCtxtGetInputWindow	(xmlParserCtxt *ctxt,
+					 int inputIndex,
+					 const xmlChar **startOut,
+					 int *sizeInOut,
+					 int *offsetOut);
 XMLPUBFUN void
-		xmlCtxtSetErrorHandler	(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetErrorHandler	(xmlParserCtxt *ctxt,
 					 xmlStructuredErrorFunc handler,
 					 void *data);
 XMLPUBFUN void
-		xmlCtxtSetResourceLoader(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetResourceLoader(xmlParserCtxt *ctxt,
 					 xmlResourceLoader loader,
 					 void *vctxt);
 XMLPUBFUN void
-		xmlCtxtSetCharEncConvImpl(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetCharEncConvImpl(xmlParserCtxt *ctxt,
 					 xmlCharEncConvImpl impl,
 					 void *vctxt);
 XMLPUBFUN void
-		xmlCtxtSetMaxAmplification(xmlParserCtxtPtr ctxt,
+		xmlCtxtSetMaxAmplification(xmlParserCtxt *ctxt,
 					 unsigned maxAmpl);
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlReadDoc		(const xmlChar *cur,
 					 const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlReadFile		(const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlReadMemory		(const char *buffer,
 					 int size,
 					 const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlReadFd		(int fd,
 					 const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
+XMLPUBFUN xmlDoc *
 		xmlReadIO		(xmlInputReadCallback ioread,
 					 xmlInputCloseCallback ioclose,
 					 void *ioctx,
 					 const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
-		xmlCtxtParseDocument	(xmlParserCtxtPtr ctxt,
-					 xmlParserInputPtr input);
-XMLPUBFUN xmlNodePtr
-		xmlCtxtParseContent	(xmlParserCtxtPtr ctxt,
-					 xmlParserInputPtr input,
-					 xmlNodePtr node,
+XMLPUBFUN xmlDoc *
+		xmlCtxtParseDocument	(xmlParserCtxt *ctxt,
+					 xmlParserInput *input);
+XMLPUBFUN xmlNode *
+		xmlCtxtParseContent	(xmlParserCtxt *ctxt,
+					 xmlParserInput *input,
+					 xmlNode *node,
 					 int hasTextDecl);
-XMLPUBFUN xmlDocPtr
-		xmlCtxtReadDoc		(xmlParserCtxtPtr ctxt,
+XMLPUBFUN xmlDoc *
+		xmlCtxtReadDoc		(xmlParserCtxt *ctxt,
 					 const xmlChar *cur,
 					 const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
-		xmlCtxtReadFile		(xmlParserCtxtPtr ctxt,
+XMLPUBFUN xmlDoc *
+		xmlCtxtReadFile		(xmlParserCtxt *ctxt,
 					 const char *filename,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
-		xmlCtxtReadMemory		(xmlParserCtxtPtr ctxt,
+XMLPUBFUN xmlDoc *
+		xmlCtxtReadMemory		(xmlParserCtxt *ctxt,
 					 const char *buffer,
 					 int size,
 					 const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
-		xmlCtxtReadFd		(xmlParserCtxtPtr ctxt,
+XMLPUBFUN xmlDoc *
+		xmlCtxtReadFd		(xmlParserCtxt *ctxt,
 					 int fd,
 					 const char *URL,
 					 const char *encoding,
 					 int options);
-XMLPUBFUN xmlDocPtr
-		xmlCtxtReadIO		(xmlParserCtxtPtr ctxt,
+XMLPUBFUN xmlDoc *
+		xmlCtxtReadIO		(xmlParserCtxt *ctxt,
 					 xmlInputReadCallback ioread,
 					 xmlInputCloseCallback ioclose,
 					 void *ioctx,
@@ -1553,74 +2048,107 @@ XMLPUBFUN xmlDocPtr
 					 const char *encoding,
 					 int options);
 
-/**
+/*
  * New input API
  */
 
 XMLPUBFUN xmlParserErrors
 xmlNewInputFromUrl(const char *url, xmlParserInputFlags flags,
-                   xmlParserInputPtr *out);
-XMLPUBFUN xmlParserInputPtr
+                   xmlParserInput **out);
+XMLPUBFUN xmlParserInput *
 xmlNewInputFromMemory(const char *url, const void *mem, size_t size,
                       xmlParserInputFlags flags);
-XMLPUBFUN xmlParserInputPtr
+XMLPUBFUN xmlParserInput *
 xmlNewInputFromString(const char *url, const char *str,
                       xmlParserInputFlags flags);
-XMLPUBFUN xmlParserInputPtr
+XMLPUBFUN xmlParserInput *
 xmlNewInputFromFd(const char *url, int fd, xmlParserInputFlags flags);
-XMLPUBFUN xmlParserInputPtr
+XMLPUBFUN xmlParserInput *
 xmlNewInputFromIO(const char *url, xmlInputReadCallback ioRead,
                   xmlInputCloseCallback ioClose, void *ioCtxt,
                   xmlParserInputFlags flags);
 XMLPUBFUN xmlParserErrors
-xmlInputSetEncodingHandler(xmlParserInputPtr input,
-                           xmlCharEncodingHandlerPtr handler);
+xmlInputSetEncodingHandler(xmlParserInput *input,
+                           xmlCharEncodingHandler *handler);
 
 /*
  * Library wide options
  */
+
 /**
- * xmlFeature:
- *
  * Used to examine the existence of features that can be enabled
  * or disabled at compile-time.
  * They used to be called XML_FEATURE_xxx but this clashed with Expat
  */
 typedef enum {
+    /** Multithreading support */
     XML_WITH_THREAD = 1,
+    /** @deprecated Always available */
     XML_WITH_TREE = 2,
+    /** Serialization support */
     XML_WITH_OUTPUT = 3,
+    /** Push parser */
     XML_WITH_PUSH = 4,
+    /** XML Reader */
     XML_WITH_READER = 5,
+    /** Streaming patterns */
     XML_WITH_PATTERN = 6,
+    /** XML Writer */
     XML_WITH_WRITER = 7,
+    /** Legacy SAX1 API */
     XML_WITH_SAX1 = 8,
+    /** @deprecated FTP support was removed */
     XML_WITH_FTP = 9,
+    /** @deprecated HTTP support was removed */
     XML_WITH_HTTP = 10,
+    /** DTD validation */
     XML_WITH_VALID = 11,
+    /** HTML parser */
     XML_WITH_HTML = 12,
+    /** Legacy symbols */
     XML_WITH_LEGACY = 13,
+    /** Canonical XML */
     XML_WITH_C14N = 14,
+    /** XML Catalogs */
     XML_WITH_CATALOG = 15,
+    /** XPath */
     XML_WITH_XPATH = 16,
+    /** XPointer */
     XML_WITH_XPTR = 17,
+    /** XInclude */
     XML_WITH_XINCLUDE = 18,
+    /** iconv */
     XML_WITH_ICONV = 19,
+    /** Built-in ISO-8859-X */
     XML_WITH_ISO8859X = 20,
+    /** @deprecated Removed */
     XML_WITH_UNICODE = 21,
+    /** Regular expressions */
     XML_WITH_REGEXP = 22,
+    /** @deprecated Same as XML_WITH_REGEXP */
     XML_WITH_AUTOMATA = 23,
+    /** @deprecated Removed */
     XML_WITH_EXPR = 24,
+    /** XML Schemas */
     XML_WITH_SCHEMAS = 25,
+    /** Schematron */
     XML_WITH_SCHEMATRON = 26,
+    /** Loadable modules */
     XML_WITH_MODULES = 27,
+    /** Debugging API */
     XML_WITH_DEBUG = 28,
+    /** @deprecated Removed */
     XML_WITH_DEBUG_MEM = 29,
-    XML_WITH_DEBUG_RUN = 30, /* unused */
+    /** @deprecated Removed */
+    XML_WITH_DEBUG_RUN = 30,
+    /** GZIP compression */
     XML_WITH_ZLIB = 31,
+    /** ICU */
     XML_WITH_ICU = 32,
+    /** @deprecated LZMA support was removed */
     XML_WITH_LZMA = 33,
-    XML_WITH_RELAXNG = 34, /* since 2.14.0 */
+    /** RELAXNG, since 2.14 */
+    XML_WITH_RELAXNG = 34,
     XML_WITH_NONE = 99999 /* just to be sure of allocation size */
 } xmlFeature;