From 17049f05f9ef09b3dc2a9c5d1de3f21de7c03193 Mon Sep 17 00:00:00 2001 From: Mike Hommey Date: Tue, 13 Sep 2005 09:58:33 +0000 Subject: Load /tmp/tmp.2Zlqcz/libxml2-2.6.22 into packages/libxml2/branches/upstream/current. --- doc/devhelp/libxml2-xpath.html | 518 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 518 insertions(+) create mode 100644 doc/devhelp/libxml2-xpath.html (limited to 'doc/devhelp/libxml2-xpath.html') diff --git a/doc/devhelp/libxml2-xpath.html b/doc/devhelp/libxml2-xpath.html new file mode 100644 index 0000000..4d1a4cc --- /dev/null +++ b/doc/devhelp/libxml2-xpath.html @@ -0,0 +1,518 @@ + + + + + xpath: XML Path Language implementation + + + + + + + + + + + + + + + +
+ + Prev + + + + Up + + + + Home + + + + Next + + libxml2 Reference Manual
+

+ xpath +

+

xpath - XML Path Language implementation

+

API for the XML Path Language implementation XML Path Language implementation XPath is a language for addressing parts of an XML document, designed to be used by both XSLT and XPointer

+

Author(s): Daniel Veillard

+
+

Synopsis

+ 
#define xmlXPathNodeSetGetLength(ns);
+#define XML_XPATH_CHECKNS;
+#define XML_XPATH_NOVAR;
+#define xmlXPathNodeSetItem(ns, index);
+#define xmlXPathNodeSetIsEmpty(ns);
+typedef enum xmlXPathObjectType;
+typedef xmlXPathVariable * xmlXPathVariablePtr;
+typedef struct _xmlXPathContext xmlXPathContext;
+typedef enum xmlXPathError;
+typedef struct _xmlXPathFunct xmlXPathFunct;
+typedef xmlXPathType * xmlXPathTypePtr;
+typedef struct _xmlXPathType xmlXPathType;
+typedef xmlNodeSet * xmlNodeSetPtr;
+typedef xmlXPathFunct * xmlXPathFuncPtr;
+typedef xmlXPathCompExpr * xmlXPathCompExprPtr;
+typedef struct _xmlXPathObject xmlXPathObject;
+typedef struct _xmlXPathCompExpr xmlXPathCompExpr;
+typedef xmlXPathContext * xmlXPathContextPtr;
+typedef xmlXPathParserContext * xmlXPathParserContextPtr;
+typedef struct _xmlNodeSet xmlNodeSet;
+typedef struct _xmlXPathVariable xmlXPathVariable;
+typedef xmlXPathObject * xmlXPathObjectPtr;
+typedef struct _xmlXPathAxis xmlXPathAxis;
+typedef xmlXPathAxis * xmlXPathAxisPtr;
+typedef struct _xmlXPathParserContext xmlXPathParserContext;
+int	xmlXPathCastNodeSetToBoolean	(xmlNodeSetPtr ns);
+typedef xmlXPathFunction xmlXPathFuncLookupFunc	(void * ctxt, 
						 const xmlChar * name, 
						 const xmlChar * ns_uri);
+xmlChar *	xmlXPathCastNodeToString	(xmlNodePtr node);
+int	xmlXPathIsNaN			(double val);
+xmlXPathObjectPtr	xmlXPathConvertString	(xmlXPathObjectPtr val);
+xmlXPathObjectPtr	xmlXPathConvertBoolean	(xmlXPathObjectPtr val);
+int	xmlXPathIsInf			(double val);
+long	xmlXPathOrderDocElems		(xmlDocPtr doc);
+xmlNodeSetPtr	xmlXPathNodeSetCreate	(xmlNodePtr val);
+double	xmlXPathCastBooleanToNumber	(int val);
+double	xmlXPathCastNodeToNumber	(xmlNodePtr node);
+double	xmlXPathCastStringToNumber	(const xmlChar * val);
+typedef xmlXPathObjectPtr xmlXPathAxisFunc	(xmlXPathParserContextPtr ctxt, 
						 xmlXPathObjectPtr cur);
+double	xmlXPathCastToNumber		(xmlXPathObjectPtr val);
+int	xmlXPathCastStringToBoolean	(const xmlChar * val);
+xmlChar *	xmlXPathCastNumberToString	(double val);
+typedef xmlXPathObjectPtr xmlXPathVariableLookupFunc	(void * ctxt, 
							 const xmlChar * name, 
							 const xmlChar * ns_uri);
+void	xmlXPathFreeObject		(xmlXPathObjectPtr obj);
+int	xmlXPathEvalPredicate		(xmlXPathContextPtr ctxt, 
					 xmlXPathObjectPtr res);
+void	xmlXPathFreeContext		(xmlXPathContextPtr ctxt);
+xmlXPathObjectPtr	xmlXPathObjectCopy	(xmlXPathObjectPtr val);
+void	xmlXPathFreeNodeSetList		(xmlXPathObjectPtr obj);
+xmlXPathObjectPtr	xmlXPathEval	(const xmlChar * str, 
					 xmlXPathContextPtr ctx);
+xmlChar *	xmlXPathCastNodeSetToString	(xmlNodeSetPtr ns);
+xmlXPathObjectPtr	xmlXPathCompiledEval	(xmlXPathCompExprPtr comp, 
						 xmlXPathContextPtr ctx);
+xmlXPathObjectPtr	xmlXPathEvalExpression	(const xmlChar * str, 
						 xmlXPathContextPtr ctxt);
+void	xmlXPathInit			(void);
+xmlXPathCompExprPtr	xmlXPathCtxtCompile	(xmlXPathContextPtr ctxt, 
						 const xmlChar * str);
+typedef int xmlXPathConvertFunc		(xmlXPathObjectPtr obj, 
					 int type);
+typedef void xmlXPathFunction		(xmlXPathParserContextPtr ctxt, 
					 int nargs);
+int	xmlXPathCmpNodes		(xmlNodePtr node1, 
					 xmlNodePtr node2);
+xmlChar *	xmlXPathCastToString	(xmlXPathObjectPtr val);
+typedef void xmlXPathEvalFunc		(xmlXPathParserContextPtr ctxt, 
					 int nargs);
+xmlChar *	xmlXPathCastBooleanToString	(int val);
+int	xmlXPathCastNumberToBoolean	(double val);
+void	xmlXPathFreeNodeSet		(xmlNodeSetPtr obj);
+void	xmlXPathFreeCompExpr		(xmlXPathCompExprPtr comp);
+xmlXPathContextPtr	xmlXPathNewContext	(xmlDocPtr doc);
+xmlXPathObjectPtr	xmlXPathConvertNumber	(xmlXPathObjectPtr val);
+xmlXPathCompExprPtr	xmlXPathCompile	(const xmlChar * str);
+double	xmlXPathCastNodeSetToNumber	(xmlNodeSetPtr ns);
+int	xmlXPathCastToBoolean		(xmlXPathObjectPtr val);
+
+
+
+

Description

+
+
+

Details

+
+

Macro XML_XPATH_CHECKNS

#define XML_XPATH_CHECKNS;
+

check namespaces at compilation

+
+
+

Macro XML_XPATH_NOVAR

#define XML_XPATH_NOVAR;
+

forbid variables in expression

+
+
+

Macro xmlXPathNodeSetGetLength

#define xmlXPathNodeSetGetLength(ns);
+

Implement a functionality similar to the DOM NodeList.length. Returns the number of nodes in the node-set.

ns:a node-set
+
+
+

Macro xmlXPathNodeSetIsEmpty

#define xmlXPathNodeSetIsEmpty(ns);
+

Checks whether @ns is empty or not. Returns %TRUE if @ns is an empty node-set.

ns:a node-set
+
+
+

Macro xmlXPathNodeSetItem

#define xmlXPathNodeSetItem(ns, index);
+

Implements a functionality similar to the DOM NodeList.item(). Returns the xmlNodePtr at the given @index in @ns or NULL if @index is out of range (0 to length-1)

ns:a node-set
index:index of a node in the set
+
+
+

Structure xmlNodeSet

struct _xmlNodeSet {
+    int	nodeNr	: number of nodes in the set
+    int	nodeMax	: size of the array as allocated
+    xmlNodePtr *	nodeTab	: array of nodes in no particular order @@ with_ns to check wether name
+} xmlNodeSet;
+

+

+
+

Typedef xmlNodeSetPtr

xmlNodeSet * xmlNodeSetPtr;
+

+

+
+

Structure xmlXPathAxis

struct _xmlXPathAxis {
+    const xmlChar *	name	: the axis name
+    xmlXPathAxisFunc	func	: the search function
+} xmlXPathAxis;
+

+

+
+

Typedef xmlXPathAxisPtr

xmlXPathAxis * xmlXPathAxisPtr;
+

+

+
+

Structure xmlXPathCompExpr

struct _xmlXPathCompExpr {
+The content of this structure is not made public by the API.
+} xmlXPathCompExpr;
+

+

+
+

Typedef xmlXPathCompExprPtr

xmlXPathCompExpr * xmlXPathCompExprPtr;
+

+

+
+

Structure xmlXPathContext

struct _xmlXPathContext {
+    xmlDocPtr	doc	: The current document
+    xmlNodePtr	node	: The current node
+    int	nb_variables_unused	: unused (hash table)
+    int	max_variables_unused	: unused (hash table)
+    xmlHashTablePtr	varHash	: Hash table of defined variables
+    int	nb_types	: number of defined types
+    int	max_types	: max number of types
+    xmlXPathTypePtr	types	: Array of defined types
+    int	nb_funcs_unused	: unused (hash table)
+    int	max_funcs_unused	: unused (hash table)
+    xmlHashTablePtr	funcHash	: Hash table of defined funcs
+    int	nb_axis	: number of defined axis
+    int	max_axis	: max number of axis
+    xmlXPathAxisPtr	axis	: Array of defined axis the namespace nodes of the context node
+    xmlNsPtr *	namespaces	: Array of namespaces
+    int	nsNr	: number of namespace in scope
+    void *	user	: function to free extra variables
+    int	contextSize	: the context size
+    int	proximityPosition	: the proximity position extra stuff for XPointer
+    int	xptr	: it this an XPointer context
+    xmlNodePtr	here	: for here()
+    xmlNodePtr	origin	: for origin() the set of namespace declarations in scope for the expre
+    xmlHashTablePtr	nsHash	: The namespaces hash table
+    xmlXPathVariableLookupFunc	varLookupFunc	: variable lookup func
+    void *	varLookupData	: variable lookup data Possibility to link in an extra item
+    void *	extra	: needed for XSLT The function name and URI when calling a function
+    const xmlChar *	function
+    const xmlChar *	functionURI	: function lookup function and data
+    xmlXPathFuncLookupFunc	funcLookupFunc	: function lookup func
+    void *	funcLookupData	: function lookup data temporary namespace lists kept for walking the n
+    xmlNsPtr *	tmpNsList	: Array of namespaces
+    int	tmpNsNr	: number of namespace in scope error reporting mechanism
+    void *	userData	: user specific data block
+    xmlStructuredErrorFunc	error	: the callback in case of errors
+    xmlError	lastError	: the last error
+    xmlNodePtr	debugNode	: the source node XSLT dictionnary
+    xmlDictPtr	dict	: dictionnary if any
+    int	flags	: flags to control compilation
+} xmlXPathContext;
+

+

+
+

Typedef xmlXPathContextPtr

xmlXPathContext * xmlXPathContextPtr;
+

+

+
+

Enum xmlXPathError

enum xmlXPathError {
+    XPATH_EXPRESSION_OK = 0
+    XPATH_NUMBER_ERROR = 1
+    XPATH_UNFINISHED_LITERAL_ERROR = 2
+    XPATH_START_LITERAL_ERROR = 3
+    XPATH_VARIABLE_REF_ERROR = 4
+    XPATH_UNDEF_VARIABLE_ERROR = 5
+    XPATH_INVALID_PREDICATE_ERROR = 6
+    XPATH_EXPR_ERROR = 7
+    XPATH_UNCLOSED_ERROR = 8
+    XPATH_UNKNOWN_FUNC_ERROR = 9
+    XPATH_INVALID_OPERAND = 10
+    XPATH_INVALID_TYPE = 11
+    XPATH_INVALID_ARITY = 12
+    XPATH_INVALID_CTXT_SIZE = 13
+    XPATH_INVALID_CTXT_POSITION = 14
+    XPATH_MEMORY_ERROR = 15
+    XPTR_SYNTAX_ERROR = 16
+    XPTR_RESOURCE_ERROR = 17
+    XPTR_SUB_RESOURCE_ERROR = 18
+    XPATH_UNDEF_PREFIX_ERROR = 19
+    XPATH_ENCODING_ERROR = 20
+    XPATH_INVALID_CHAR_ERROR = 21
+    XPATH_INVALID_CTXT = 22
+};
+

+

+
+

Typedef xmlXPathFuncPtr

xmlXPathFunct * xmlXPathFuncPtr;
+

+

+
+

Structure xmlXPathFunct

struct _xmlXPathFunct {
+    const xmlChar *	name	: the function name
+    xmlXPathEvalFunc	func	: the evaluation function
+} xmlXPathFunct;
+

+

+
+

Structure xmlXPathObject

struct _xmlXPathObject {
+    xmlXPathObjectType	type
+    xmlNodeSetPtr	nodesetval
+    int	boolval
+    double	floatval
+    xmlChar *	stringval
+    void *	user
+    int	index
+    void *	user2
+    int	index2
+} xmlXPathObject;
+

+

+
+

Typedef xmlXPathObjectPtr

xmlXPathObject * xmlXPathObjectPtr;
+

+

+
+

Enum xmlXPathObjectType

enum xmlXPathObjectType {
+    XPATH_UNDEFINED = 0
+    XPATH_NODESET = 1
+    XPATH_BOOLEAN = 2
+    XPATH_NUMBER = 3
+    XPATH_STRING = 4
+    XPATH_POINT = 5
+    XPATH_RANGE = 6
+    XPATH_LOCATIONSET = 7
+    XPATH_USERS = 8
+    XPATH_XSLT_TREE = 9 /*  An XSLT value tree, non modifiable */
+};
+

+

+
+

Structure xmlXPathParserContext

struct _xmlXPathParserContext {
+    const xmlChar *	cur	: the current char being parsed
+    const xmlChar *	base	: the full expression
+    int	error	: error code
+    xmlXPathContextPtr	context	: the evaluation context
+    xmlXPathObjectPtr	value	: the current value
+    int	valueNr	: number of values stacked
+    int	valueMax	: max number of values stacked
+    xmlXPathObjectPtr *	valueTab	: stack of values
+    xmlXPathCompExprPtr	comp	: the precompiled expression
+    int	xptr	: it this an XPointer expression
+    xmlNodePtr	ancestor	: used for walking preceding axis
+} xmlXPathParserContext;
+

+

+
+

Typedef xmlXPathParserContextPtr

xmlXPathParserContext * xmlXPathParserContextPtr;
+

+

+
+

Structure xmlXPathType

struct _xmlXPathType {
+    const xmlChar *	name	: the type name
+    xmlXPathConvertFunc	func	: the conversion function
+} xmlXPathType;
+

+

+
+

Typedef xmlXPathTypePtr

xmlXPathType * xmlXPathTypePtr;
+

+

+
+

Structure xmlXPathVariable

struct _xmlXPathVariable {
+    const xmlChar *	name	: the variable name
+    xmlXPathObjectPtr	value	: the value
+} xmlXPathVariable;
+

+

+
+

Typedef xmlXPathVariablePtr

xmlXPathVariable * xmlXPathVariablePtr;
+

+

+
+

Function type xmlXPathAxisFunc

xmlXPathObjectPtr	xmlXPathAxisFunc	(xmlXPathParserContextPtr ctxt, 
						 xmlXPathObjectPtr cur)

+

An axis traversal function. To traverse an axis, the engine calls the first time with cur == NULL and repeat until the function returns NULL indicating the end of the axis traversal.

+
ctxt:the XPath interpreter context
cur:the previous node being explored on that axis
Returns:the next node in that axis or NULL if at the end of the axis.
+
+

Function type xmlXPathConvertFunc

int	xmlXPathConvertFunc		(xmlXPathObjectPtr obj, 
					 int type)

+

A conversion function is associated to a type and used to cast the new type to primitive values.

+
obj:an XPath object
type:the number of the target type
Returns:-1 in case of error, 0 otherwise
+
+

Function type xmlXPathEvalFunc

void	xmlXPathEvalFunc		(xmlXPathParserContextPtr ctxt, 
					 int nargs)

+

An XPath evaluation function, the parameters are on the XPath context stack.

+
ctxt:an XPath parser context
nargs:the number of arguments passed to the function
+
+

Function type xmlXPathFuncLookupFunc

xmlXPathFunction	xmlXPathFuncLookupFunc	(void * ctxt, 
						 const xmlChar * name, 
						 const xmlChar * ns_uri)

+

Prototype for callbacks used to plug function lookup in the XPath engine.

+
ctxt:an XPath context
name:name of the function
ns_uri:the namespace name hosting this function
Returns:the XPath function or NULL if not found.
+
+

Function type xmlXPathFunction

void	xmlXPathFunction		(xmlXPathParserContextPtr ctxt, 
					 int nargs)

+

An XPath function. The arguments (if any) are popped out from the context stack and the result is pushed on the stack.

+
ctxt:the XPath interprestation context
nargs:the number of arguments
+
+

Function type xmlXPathVariableLookupFunc

xmlXPathObjectPtr	xmlXPathVariableLookupFunc	(void * ctxt, 
							 const xmlChar * name, 
							 const xmlChar * ns_uri)

+

Prototype for callbacks used to plug variable lookup in the XPath engine.

+
ctxt:an XPath context
name:name of the variable
ns_uri:the namespace name hosting this variable
Returns:the XPath object value or NULL if not found.
+
+

Variable xmlXPathNAN

double xmlXPathNAN;
+

+

+
+

Variable xmlXPathNINF

double xmlXPathNINF;
+

+

+
+

Variable xmlXPathPINF

double xmlXPathPINF;
+

+

+
+

xmlXPathCastBooleanToNumber ()

double	xmlXPathCastBooleanToNumber	(int val)

+

Converts a boolean to its number value

+
val:a boolean
Returns:the number value
+
+

xmlXPathCastBooleanToString ()

xmlChar *	xmlXPathCastBooleanToString	(int val)

+

Converts a boolean to its string value.

+
val:a boolean
Returns:a newly allocated string.
+
+

xmlXPathCastNodeSetToBoolean ()

int	xmlXPathCastNodeSetToBoolean	(xmlNodeSetPtr ns)

+

Converts a node-set to its boolean value

+
ns:a node-set
Returns:the boolean value
+
+

xmlXPathCastNodeSetToNumber ()

double	xmlXPathCastNodeSetToNumber	(xmlNodeSetPtr ns)

+

Converts a node-set to its number value

+
ns:a node-set
Returns:the number value
+
+

xmlXPathCastNodeSetToString ()

xmlChar *	xmlXPathCastNodeSetToString	(xmlNodeSetPtr ns)

+

Converts a node-set to its string value.

+
ns:a node-set
Returns:a newly allocated string.
+
+

xmlXPathCastNodeToNumber ()

double	xmlXPathCastNodeToNumber	(xmlNodePtr node)

+

Converts a node to its number value

+
node:a node
Returns:the number value
+
+

xmlXPathCastNodeToString ()

xmlChar *	xmlXPathCastNodeToString	(xmlNodePtr node)

+

Converts a node to its string value.

+
node:a node
Returns:a newly allocated string.
+
+

xmlXPathCastNumberToBoolean ()

int	xmlXPathCastNumberToBoolean	(double val)

+

Converts a number to its boolean value

+
val:a number
Returns:the boolean value
+
+

xmlXPathCastNumberToString ()

xmlChar *	xmlXPathCastNumberToString	(double val)

+

Converts a number to its string value.

+
val:a number
Returns:a newly allocated string.
+
+

xmlXPathCastStringToBoolean ()

int	xmlXPathCastStringToBoolean	(const xmlChar * val)

+

Converts a string to its boolean value

+
val:a string
Returns:the boolean value
+
+

xmlXPathCastStringToNumber ()

double	xmlXPathCastStringToNumber	(const xmlChar * val)

+

Converts a string to its number value

+
val:a string
Returns:the number value
+
+

xmlXPathCastToBoolean ()

int	xmlXPathCastToBoolean		(xmlXPathObjectPtr val)

+

Converts an XPath object to its boolean value

+
val:an XPath object
Returns:the boolean value
+
+

xmlXPathCastToNumber ()

double	xmlXPathCastToNumber		(xmlXPathObjectPtr val)

+

Converts an XPath object to its number value

+
val:an XPath object
Returns:the number value
+
+

xmlXPathCastToString ()

xmlChar *	xmlXPathCastToString	(xmlXPathObjectPtr val)

+

Converts an existing object to its string() equivalent

+
val:an XPath object
Returns:the string value of the object, NULL in case of error. A new string is allocated only if needed (@val isn't a string object).
+
+

xmlXPathCmpNodes ()

int	xmlXPathCmpNodes		(xmlNodePtr node1, 
					 xmlNodePtr node2)

+

Compare two nodes w.r.t document order

+
node1:the first node
node2:the second node
Returns:-2 in case of error 1 if first point < second point, 0 if it's the same node, -1 otherwise
+
+

xmlXPathCompile ()

xmlXPathCompExprPtr	xmlXPathCompile	(const xmlChar * str)

+

Compile an XPath expression

+
str:the XPath expression
Returns:the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object.
+
+

xmlXPathCompiledEval ()

xmlXPathObjectPtr	xmlXPathCompiledEval	(xmlXPathCompExprPtr comp, 
						 xmlXPathContextPtr ctx)

+

Evaluate the Precompiled XPath expression in the given context.

+
comp:the compiled XPath expression
ctx:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.
+
+

xmlXPathConvertBoolean ()

xmlXPathObjectPtr	xmlXPathConvertBoolean	(xmlXPathObjectPtr val)

+

Converts an existing object to its boolean() equivalent

+
val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)
+
+

xmlXPathConvertNumber ()

xmlXPathObjectPtr	xmlXPathConvertNumber	(xmlXPathObjectPtr val)

+

Converts an existing object to its number() equivalent

+
val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)
+
+

xmlXPathConvertString ()

xmlXPathObjectPtr	xmlXPathConvertString	(xmlXPathObjectPtr val)

+

Converts an existing object to its string() equivalent

+
val:an XPath object
Returns:the new object, the old one is freed (or the operation is done directly on @val)
+
+

xmlXPathCtxtCompile ()

xmlXPathCompExprPtr	xmlXPathCtxtCompile	(xmlXPathContextPtr ctxt, 
						 const xmlChar * str)

+

Compile an XPath expression

+
ctxt:an XPath context
str:the XPath expression
Returns:the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object.
+
+

xmlXPathEval ()

xmlXPathObjectPtr	xmlXPathEval	(const xmlChar * str, 
					 xmlXPathContextPtr ctx)

+

Evaluate the XPath Location Path in the given context.

+
str:the XPath expression
ctx:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.
+
+

xmlXPathEvalExpression ()

xmlXPathObjectPtr	xmlXPathEvalExpression	(const xmlChar * str, 
						 xmlXPathContextPtr ctxt)

+

Evaluate the XPath expression in the given context.

+
str:the XPath expression
ctxt:the XPath context
Returns:the xmlXPathObjectPtr resulting from the evaluation or NULL. the caller has to free the object.
+
+

xmlXPathEvalPredicate ()

int	xmlXPathEvalPredicate		(xmlXPathContextPtr ctxt, 
					 xmlXPathObjectPtr res)

+

Evaluate a predicate result for the current node. A PredicateExpr is evaluated by evaluating the Expr and converting the result to a boolean. If the result is a number, the result will be converted to true if the number is equal to the position of the context node in the context node list (as returned by the position function) and will be converted to false otherwise; if the result is not a number, then the result will be converted as if by a call to the boolean function.

+
ctxt:the XPath context
res:the Predicate Expression evaluation result
Returns:1 if predicate is true, 0 otherwise
+
+

xmlXPathFreeCompExpr ()

void	xmlXPathFreeCompExpr		(xmlXPathCompExprPtr comp)

+

Free up the memory allocated by @comp

+
comp:an XPATH comp
+
+

xmlXPathFreeContext ()

void	xmlXPathFreeContext		(xmlXPathContextPtr ctxt)

+

Free up an xmlXPathContext

+
ctxt:the context to free
+
+

xmlXPathFreeNodeSet ()

void	xmlXPathFreeNodeSet		(xmlNodeSetPtr obj)

+

Free the NodeSet compound (not the actual nodes !).

+
obj:the xmlNodeSetPtr to free
+
+

xmlXPathFreeNodeSetList ()

void	xmlXPathFreeNodeSetList		(xmlXPathObjectPtr obj)

+

Free up the xmlXPathObjectPtr @obj but don't deallocate the objects in the list contrary to xmlXPathFreeObject().

+
obj:an existing NodeSetList object
+
+

xmlXPathFreeObject ()

void	xmlXPathFreeObject		(xmlXPathObjectPtr obj)

+

Free up an xmlXPathObjectPtr object.

+
obj:the object to free
+
+

xmlXPathInit ()

void	xmlXPathInit			(void)

+

Initialize the XPath environment

+
+
+

xmlXPathIsInf ()

int	xmlXPathIsInf			(double val)

+

Provides a portable isinf() function to detect whether a double is a +Infinite or -Infinite. Based on trio code http://sourceforge.net/projects/ctrio/

+
val:a double value
Returns:1 vi the value is +Infinite, -1 if -Infinite, 0 otherwise
+
+

xmlXPathIsNaN ()

int	xmlXPathIsNaN			(double val)

+

Provides a portable isnan() function to detect whether a double is a NotaNumber. Based on trio code http://sourceforge.net/projects/ctrio/

+
val:a double value
Returns:1 if the value is a NaN, 0 otherwise
+
+

xmlXPathNewContext ()

xmlXPathContextPtr	xmlXPathNewContext	(xmlDocPtr doc)

+

Create a new xmlXPathContext

+
doc:the XML document
Returns:the xmlXPathContext just allocated. The caller will need to free it.
+
+

xmlXPathNodeSetCreate ()

xmlNodeSetPtr	xmlXPathNodeSetCreate	(xmlNodePtr val)

+

Create a new xmlNodeSetPtr of type double and of value @val

+
val:an initial xmlNodePtr, or NULL
Returns:the newly created object.
+
+

xmlXPathObjectCopy ()

xmlXPathObjectPtr	xmlXPathObjectCopy	(xmlXPathObjectPtr val)

+

allocate a new copy of a given object

+
val:the original object
Returns:the newly created object.
+
+

xmlXPathOrderDocElems ()

long	xmlXPathOrderDocElems		(xmlDocPtr doc)

+

Call this routine to speed up XPath computation on static documents. This stamps all the element nodes with the document order Like for line information, the order is kept in the element->content field, the value stored is actually - the node number (starting at -1) to be able to differentiate from line numbers.

+
doc:an input document
Returns:the number of elements found in the document or -1 in case of error.
+
+
+
+ + -- cgit v1.2.3 From a7e9d3f37d5e9fba4b9acaa43e7c12b6d9a669ae Mon Sep 17 00:00:00 2001 From: Mike Hommey Date: Thu, 8 Jun 2006 10:59:26 +0200 Subject: Load /tmp/libxml2-2.6.26 into libxml2/branches/upstream/current. --- ChangeLog | 241 ++ configure | 10 +- configure.in | 10 +- doc/APIchunk1.html | 2 + doc/APIchunk10.html | 1 + doc/APIchunk12.html | 7 +- doc/APIchunk13.html | 2 + doc/APIchunk14.html | 2 + doc/APIchunk15.html | 2 + doc/APIchunk17.html | 1 + doc/APIchunk19.html | 2 + doc/APIchunk21.html | 5 +- doc/APIchunk22.html | 1 + doc/APIchunk23.html | 2 + doc/APIchunk24.html | 5 + doc/APIchunk28.html | 1 + doc/APIchunk5.html | 1 + doc/APIchunk8.html | 2 + doc/APIfiles.html | 2 + doc/APIfunctions.html | 1 + doc/APIsymbols.html | 2 + doc/DOM.html | 16 +- doc/FAQ.html | 333 ++- doc/XMLinfo.html | 33 +- doc/XSLT.html | 9 +- doc/architecture.html | 7 +- doc/bugs.html | 118 +- doc/catalog.html | 324 ++- doc/contribs.html | 53 +- doc/devhelp/libxml2-xmlerror.html | 1 + doc/devhelp/libxml2-xpath.html | 8 +- doc/devhelp/libxml2.devhelp | 2 + doc/docs.html | 35 +- doc/downloads.html | 42 +- doc/encoding.html | 312 +-- doc/entities.html | 74 +- doc/example.html | 70 +- doc/help.html | 26 +- doc/html/libxml-xmlerror.html | 1 + doc/html/libxml-xpath.html | 8 +- doc/index.html | 109 +- doc/interface.html | 35 +- doc/intro.html | 40 +- doc/library.html | 137 +- doc/libxml2-api.xml | 15 +- doc/libxml2.xsa | 49 +- doc/namespaces.html | 70 +- doc/news.html | 1688 +++++++------ doc/python.html | 247 +- doc/threads.html | 23 +- doc/tree.html | 32 +- doc/upgrade.html | 188 +- doc/xml.html | 5011 +++++++++++++++++++------------------ doc/xmldtd.html | 154 +- doc/xmlio.html | 123 +- doc/xmlmem.html | 166 +- encoding.c | 3 +- include/libxml/xmlerror.h | 1 + include/libxml/xmlversion.h | 10 +- include/libxml/xpath.h | 13 +- libxml.h | 7 + libxml.spec.in | 51 +- libxml2.spec | 57 +- pattern.c | 210 +- python/libxml2-py.c | 21 + python/setup.py | 2 +- relaxng.c | 2 +- runsuite.c | 11 +- testapi.c | 58 +- tree.c | 7 - triodef.h | 4 +- xinclude.c | 2 +- xmlIO.c | 7 +- xmlschemas.c | 97 +- xpath.c | 3580 ++++++++++++++++++++++---- 75 files changed, 8538 insertions(+), 5466 deletions(-) (limited to 'doc/devhelp/libxml2-xpath.html') diff --git a/ChangeLog b/ChangeLog index 7ef389d..f6b31ef 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,244 @@ +Tue Jun 6 17:50:43 CEST 2006 Daniel Veillard + + * configure.ini NEWS doc//* libxml.spec.in : preparing release of 2.6.26 + +Tue Jun 6 17:25:23 CEST 2006 Kasimier Buchcik + + * xpath.c: Fixed self-invented a segfault in xmlXPathCtxtCompile(), + when the expression was not valid and @comp was NULL and I + tried to do the d-o-s rewrite. + +Tue Jun 6 15:19:57 CEST 2006 Daniel Veillard + + * configure.ini NEWS doc//* libxml.spec.in : preparing release of 2.6.25 + +Tue Jun 6 11:28:15 CEST 2006 Kasimier Buchcik + + * xpath.c: Enabled the compound traversal again; I added a + check to use this only if the have an expression starting + with the document node; so in the case of "//foo", we + already know at compilation-time, that there will be only + 1 initial context node. Added the rewrite also to + xmlXPathEvalExpr(). + +Tue Jun 6 10:23:10 CEST 2006 Daniel Veillard + + * xinclude.c: fix bug #343968, include='text' can't lead to a + recursion. + +Fri Jun 2 22:47:08 CEST 2006 Kasimier Buchcik + + * xpath.c: Disabled the compound traversal for the release; + I need first to assure that this is done only if we have + 1 initial node. + +Wed May 31 13:53:41 PST 2006 Aleksey Sanin + + * xpath.c: fixed memory leak in xpath error reporting + +Wed May 31 15:30:16 CEST 2006 Daniel Veillard + + * libxml.h triodef.h: applied patch from Olli Savia for LynxOS + +Wed May 31 14:33:00 CEST 2006 Kasimier Buchcik + + * xpath.c include/libxml/xpath.h runsuite.c: + Changed the name of the recently added public function + xmlXPathContextSetObjectCache() to + xmlXPathContextSetCache(); so a more generic one, in + case we decide to cache more things than only XPath + objects. + +Tue May 30 21:36:16 CEST 2006 Kasimier Buchcik + + * xpath.c: Optimized xmlXPathNodeCollectAndTest() and + xmlXPathNodeCollectAndTestNth() to evaluate a compound + traversal of 2 axes when we have a "//foo" expression. + This is done with a rewrite of the XPath AST in + xmlXPathRewriteDOSExpression(); I added an additional field + to xmlXPathStepOp for this (but the field's name should be + changed). The mechanism: the embracing descendant-or-self + axis traversal (also optimized to return only nodes which + can hold elements), will produce context nodes for the + inner traversal of the child axis. This way we avoid a full + node-collecting traversal of the descendant-or-self axis. + Some tests indicate that this can reduce execution time of + "//foo" to 50%. Together with the XPath object cache this + all significantly speeds up libxslt. + +Tue May 30 11:38:47 CEST 2006 Kasimier Buchcik + + * xmlschemas.c: A warning will now be reported in the value of + the XSD attribute 'schemaLocation' does not consist of tuples + (namespace-name, document-URI). A warning will be reported + if a schema document could not be found at the specified + location (via 'schemaLocation' or + 'noNamespaceSchemaLocation'). + * include/libxml/xmlerror.h: Added XML_SCHEMAV_MISC to + xmlParserErrors. + +Tue May 30 11:21:34 CEST 2006 Kasimier Buchcik + + * xpath.c: Enhanced xmlXPathNodeCollectAndTest() to avoid + recreation (if possible) of the node-set which is used to + collect the nodes in the current axis for the currect context + node. Especially for "//foo" this will decrease dramatically + the number of created node-sets, since for each node in the + result node-set of the evaluation of descendant-or-self::node() + a new temporary node-set was created. Added node iterator + xmlXPathNextChildElement() as a tiny optimization for + child::foo. + +Mon May 29 18:06:17 CEST 2006 Kasimier Buchcik + + * xpath.c include/libxml/xpath.h: Added an XPath object cache. + It sits on an xmlXPathContext and need to be explicitely + activated (or deactivated again) with + xmlXPathContextSetObjectCache(). The cache consists of 5 + lists for node-set, string, number, boolean and misc XPath + objects. Internally the xpath.c module will use object- + deposition and -acquisition functions which will try to reuse + as many XPath objects as possible, and fallback to normal + free/create behaviour if no cache is available or if the cache + is full. + * runsuite.c: Adjusted to deactivate the cache for XML Schema + tests if a cache-creation is turned on by default for the whole + library, e.g. for testing purposes of the cache. It is + deactivated here in order to avoid confusion of the memory leak + detection in runsuite.c. + +Wed May 24 10:54:25 CEST 2006 Kasimier Buchcik + + * xpath.c: Removed a memcpy if xmlXPathNodeSetMerge(); it + seems we really need to walk the whole list, since those + nastly namespace nodes need to be added with + xmlXPathNodeSetDupNs(); thus a pure memcpy is not possible. + A flag on the node-set indicating if namespace nodes are in + the set would help here; this is the 3rd flag which would + be usefull with node-sets. The current flags I have in mind: + 1) Is a node-set already sorted? + This would allow for rebust and optimizable sorting + behaviour. + 2) Of what type are the nodes in the set (or of mixed type)? + This would allow for faster merging of node-sets. + 3) Are namespace nodes in the set? + This would allow to skipp all the namespace node specific + special handling. Faster node-set merging if the first + set is empty; just memcpy the set. + +Mon May 22 17:14:00 CEST 2006 Kasimier Buchcik + + * xpath.c: Optimization of count(): eliminated sorting + (see bug #165547). Optimization of XPATH_OP_FILTER if the + predicate is a [1] (disable with XP_OPTIMIZED_FILTER_FIRST if + it produces trouble). Tiny opt in xmlXPathNodeSetMerge(). + +Mon May 22 13:33:12 CEST 2006 Rob Richards + + * tree.c: Revert behavior change in xmlSetProp to handle attributes + with colons in name and no namespace. + +Fri May 19 21:56:43 CEST 2006 Kasimier Buchcik + + * xpath.c: Substituted all remaining calls to xmlXPathCmpNodes() + for xmlXPathCmpNodesExt(). Tiny further enhancement of + xmlXPathCmpNodesExt(). Added additional checks in various code + parts to avoid calling sorting or merging functions if the + node-set(s) don't need them; i.e., if they are empty or contain + just one node. + +Fri May 19 13:16:58 CEST 2006 Kasimier Buchcik + + * xpath.c: Optimized the comparison for non-element nodes + in xmlXPathCmpNodesExt(); the comparison is used for sorting + of node-sets. This enhancement is related to bug #165547. + There are other places where the old comparison function + xmlXPathCmpNodes() is still called, but I currently don't + know exactly what those calls are for; thus if they can be + substituted (if it makes sense) for the new function. + +Tue May 16 16:55:13 CEST 2006 Kasimier Buchcik + + * xpath.c: Applied patch from Rob Richards, fixing a potential + memory leak in xmlXPathTryStreamCompile(), when a list of + namespaces was assigned to the XPath compilation context; + here a new namespace list was created and passed to + xmlPatterncompile(); but this list was not freed afterwards. + Additionally we avoid now in xmlXPathTryStreamCompile() to + compile the expression, if it has a colon - indicating + prefixed name tests - and no namespace list was given. The + streaming XPath mechanism needs a namespace list at + compilation time (unlike normal XPath, where we can bind + namespace names to prefixes at execution time). + * pattern.c: Enhanced to use a string dict for local-names, + ns-prefixes and and namespace-names. + Fixed xmlStreamPushInternal() not to use string-pointer + comparison if a dict is available; this won't work, since + one does not know it the given strings originate from the + same dict - and they normally don't do, since e.g. + namespaces are hold on xmlNs->href. I think this would be + worth an investigation: if we can add a @doc field to xmlNs + and put the @href in to a additionan namespace dict hold + in xmlDoc. Daniel will surely not like this idea :-) But + evaluation of tons of elements/attributes in namespaces + with xmlStrEqual() isn't the way we should go forever. + +Thu May 11 18:03:49 CEST 2006 Kasimier Buchcik + + * xmlschemas.c: Fixed bug #341337, reported by David Grohmann. + The code expected a node (xmlNodePtr) on the info for a + non-existent default attribute, which clearly cannot be + expected, since the attribute does not exist. I can only + guess that this sneaked trying to eliminate the query + for the owner-element, which is unavoidable actually. + Note that creation of default attributes won't have an + effect if validating via SAX/XMLReader; i.e., the processor + won't fire additional start-attribute events (I'm not even + sure if Libxml2 has such a SAX-event; I think it hands them + all over in the start-element event). + +Tue May 9 21:47:58 CEST 2006 Kasimier Buchcik + + * xmlschemas.c: Fixed bug #341150, reported by Michael Romer. + In xmlSchemaBuildContentModelForSubstGroup(), + xmlAutomataNewOnceTrans2() was incorrectly used instead of + xmlAutomataNewTransition2() to mimic a xs:choice for + substitution-groups. + * test/schemas/subst-group-1_1.xsd + test/schemas/subst-group-1_0.xml + result/schemas/subst-group-1_0_1 + result/schemas/subst-group-1_0_1.err: Added regression test + supplied by Michael Romer for bug #341150. + +Sat May 6 11:05:24 HKT 2006 William M. Brack + + * relaxng.c: Fixed compilation error with patch supplied by + Graham Bennett. + +Thu May 4 19:14:03 CEST 2006 Kasimier Buchcik + + * xmlschemas.c: We'll raise an internal error and stop + validation now when an entity is found in the instance + document, since we don't support automatic entity + substitution by the schema processor (yet?) - + see bug #340316, reported by Nick Wellnhofer. + +Wed May 3 15:16:00 CEST 2006 Daniel Veillard + + * configure.in: applied another Python detection patch from Joseph Sacco + * libxml.spec.in: cleanup the changelog section, asciifies the spec file + too + +Tue May 2 22:34:54 CEST 2006 Daniel Veillard + + * xmlIO.c: fix a mix of code and declarations showing up on Windows + patch from Kjartan Maraas, fixing #340404 + +Tue May 2 14:24:40 CEST 2006 Daniel Veillard + + * encoding.c: fixing bug #340398 xmlCharEncOutFunc writing to + input buffer + Fri Apr 28 18:29:22 CEST 2006 Daniel Veillard * NEWS configure.in doc//*: preparing 2.6.24 release, fixed Python diff --git a/configure b/configure index f0dc765..5bf44bb 100755 --- a/configure +++ b/configure @@ -1618,7 +1618,7 @@ host_os=`echo $ac_cv_host | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\3/'` LIBXML_MAJOR_VERSION=2 LIBXML_MINOR_VERSION=6 -LIBXML_MICRO_VERSION=24 +LIBXML_MICRO_VERSION=26 LIBXML_MICRO_VERSION_SUFFIX= LIBXML_VERSION=$LIBXML_MAJOR_VERSION.$LIBXML_MINOR_VERSION.$LIBXML_MICRO_VERSION$LIBXML_MICRO_VERSION_SUFFIX LIBXML_VERSION_INFO=`expr $LIBXML_MAJOR_VERSION + $LIBXML_MINOR_VERSION`:$LIBXML_MICRO_VERSION:$LIBXML_MINOR_VERSION @@ -26935,17 +26935,17 @@ fi -d $with_python/lib/python$PYTHON_VERSION/site-packages then PYTHON_INCLUDES=$with_python/include/python$PYTHON_VERSION - PYTHON_SITE_PACKAGES='$(libdir)/lib/python$(PYTHON_VERSION)/site-packages' + PYTHON_SITE_PACKAGES=$libdir/python$PYTHON_VERSION/site-packages else if test -r $prefix/include/python$PYTHON_VERSION/Python.h then PYTHON_INCLUDES=$prefix/include/python$PYTHON_VERSION - PYTHON_SITE_PACKAGES='$(libdir)/python$(PYTHON_VERSION)/site-packages' + PYTHON_SITE_PACKAGES=$libdir/python$PYTHON_VERSION/site-packages else if test -r /usr/include/python$PYTHON_VERSION/Python.h then PYTHON_INCLUDES=/usr/include/python$PYTHON_VERSION - PYTHON_SITE_PACKAGES='$(libdir)/python$(PYTHON_VERSION)/site-packages' + PYTHON_SITE_PACKAGES=$libdir/python$PYTHON_VERSION/site-packages else echo could not find python$PYTHON_VERSION/Python.h fi @@ -26958,7 +26958,7 @@ fi fi if test "$with_python" != "" then - pythondir=$(PYTHON_SITE_PACKAGES) + pythondir='$(PYTHON_SITE_PACKAGES)' else pythondir='$(libdir)/python$(PYTHON_VERSION)/site-packages' fi diff --git a/configure.in b/configure.in index 6951b3d..e01408a 100644 --- a/configure.in +++ b/configure.in @@ -5,7 +5,7 @@ AC_CANONICAL_HOST LIBXML_MAJOR_VERSION=2 LIBXML_MINOR_VERSION=6 -LIBXML_MICRO_VERSION=24 +LIBXML_MICRO_VERSION=26 LIBXML_MICRO_VERSION_SUFFIX= LIBXML_VERSION=$LIBXML_MAJOR_VERSION.$LIBXML_MINOR_VERSION.$LIBXML_MICRO_VERSION$LIBXML_MICRO_VERSION_SUFFIX LIBXML_VERSION_INFO=`expr $LIBXML_MAJOR_VERSION + $LIBXML_MINOR_VERSION`:$LIBXML_MICRO_VERSION:$LIBXML_MINOR_VERSION @@ -678,17 +678,17 @@ if test "$with_python" != "no" ; then -d $with_python/lib/python$PYTHON_VERSION/site-packages then PYTHON_INCLUDES=$with_python/include/python$PYTHON_VERSION - PYTHON_SITE_PACKAGES='$(libdir)/lib/python$(PYTHON_VERSION)/site-packages' + PYTHON_SITE_PACKAGES=$libdir/python$PYTHON_VERSION/site-packages else if test -r $prefix/include/python$PYTHON_VERSION/Python.h then PYTHON_INCLUDES=$prefix/include/python$PYTHON_VERSION - PYTHON_SITE_PACKAGES='$(libdir)/python$(PYTHON_VERSION)/site-packages' + PYTHON_SITE_PACKAGES=$libdir/python$PYTHON_VERSION/site-packages else if test -r /usr/include/python$PYTHON_VERSION/Python.h then PYTHON_INCLUDES=/usr/include/python$PYTHON_VERSION - PYTHON_SITE_PACKAGES='$(libdir)/python$(PYTHON_VERSION)/site-packages' + PYTHON_SITE_PACKAGES=$libdir/python$PYTHON_VERSION/site-packages else echo could not find python$PYTHON_VERSION/Python.h fi @@ -701,7 +701,7 @@ if test "$with_python" != "no" ; then fi if test "$with_python" != "" then - pythondir=$(PYTHON_SITE_PACKAGES) + pythondir='$(PYTHON_SITE_PACKAGES)' else pythondir='$(libdir)/python$(PYTHON_VERSION)/site-packages' fi diff --git a/doc/APIchunk1.html b/doc/APIchunk1.html index ca14e32..7c9ff72 100644 --- a/doc/APIchunk1.html +++ b/doc/APIchunk1.html @@ -81,6 +81,7 @@ A:link, A:visited, A:active { text-decoration: underline }
CJKUnifiedIdeographsExtensionB
xmlUCSIsCJKUnifiedIdeographsExtensionB
CVS
LIBXML_VERSION_EXTRA
CWD
xmlNanoFTPCwd
+
Cache
_xmlXPathContext
Call
htmlInitAutoClose
xmlInitParser
xmlXPathOrderDocElems
@@ -309,6 +310,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlExpNewCtxt
xmlNewDoc
xmlXIncludeNewContext
+xmlXPathContextSetCache
Creation
xmlNewCDataBlock
xmlNewCharRef
xmlNewChild
diff --git a/doc/APIchunk10.html b/doc/APIchunk10.html index c2e8d33..0486624 100644 --- a/doc/APIchunk10.html +++ b/doc/APIchunk10.html @@ -123,6 +123,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlTextReaderSchemaValidate
xmlTextReaderSchemaValidateCtxt
xmlTextReaderSetSchema
+
activates
xmlXPathContextSetCache
activation
xmlGetLineNo
acts
xmlGetProp
actual
xmlGetUTF8Char
diff --git a/doc/APIchunk12.html b/doc/APIchunk12.html index 8f93a9f..1c552b1 100644 --- a/doc/APIchunk12.html +++ b/doc/APIchunk12.html @@ -37,7 +37,10 @@ A:link, A:visited, A:active { text-decoration: underline } w-w x-x y-z -

Letter c:

calculated
xmlStrncatNew
+

Letter c:

cache
xmlXPathContextSetCache
+
cached
xmlXPathContextSetCache
+
caching:
xmlXPathContextSetCache
+
calculated
xmlStrncatNew
calculates
xmlUTF8Size
calling
_xmlXPathContext
xmlBuildRelativeURI
@@ -839,6 +842,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlAutomataNewTransition2
xmlCreateURI
xmlStrncatNew
+xmlXPathContextSetCache
creating
xmlDOMWrapAdoptNode
xmlDOMWrapCloneNode
xmlDOMWrapReconcileNamespaces
@@ -869,6 +873,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlMemGet
xmlMemUsed
xmlOutputBufferCreateFilename
+xmlXPathContextSetCache
custom
xmlDOMWrapAdoptNode
xmlDOMWrapCloneNode
xmlSaveSetAttrEscape
diff --git a/doc/APIchunk13.html b/doc/APIchunk13.html index 96643e3..5980cc2 100644 --- a/doc/APIchunk13.html +++ b/doc/APIchunk13.html @@ -221,6 +221,7 @@ A:link, A:visited, A:active { text-decoration: underline }
delegation
xmlCatalogSetDefaultPrefer
delete
xmlNanoFTPDele
deletion
xmlCatalogSetDefaultPrefer
+
dependant
xmlXPathContextSetCache
depending
xmlIsID
xmlIsRef
xmlListDataCompare
@@ -455,6 +456,7 @@ A:link, A:visited, A:active { text-decoration: underline }
disabled
XML_CAST_FPTR
_xmlParserCtxt
xmlParseURIRaw
+
disables
xmlXPathContextSetCache
disabling
xmlNoNetExternalEntityLoader
disallowed
XML_SCHEMAS_ELEM_BLOCK_EXTENSION
XML_SCHEMAS_ELEM_BLOCK_RESTRICTION
diff --git a/doc/APIchunk14.html b/doc/APIchunk14.html index eb1716e..f5134af 100644 --- a/doc/APIchunk14.html +++ b/doc/APIchunk14.html @@ -50,6 +50,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlXPathIdFunction
xmlXPathSubstringFunction
edition
xmlCheckLanguageID
+
effect
xmlXPathContextSetCache
effective
xmlLoadCatalog
xmlLoadCatalogs
efficiency
xmlBuildRelativeURI
@@ -118,6 +119,7 @@ A:link, A:visited, A:active { text-decoration: underline }
enable
xmlCatalogSetDebug
enabled
xmlSaveFile
xmlSaveFormatFile
+
enables
xmlXPathContextSetCache
enabling
xmlLineNumbersDefault
xmlPedanticParserDefault
enc
xmlParserInputBufferCreateFilename
diff --git a/doc/APIchunk15.html b/doc/APIchunk15.html index 8b51338..4ac0a55 100644 --- a/doc/APIchunk15.html +++ b/doc/APIchunk15.html @@ -243,6 +243,7 @@ A:link, A:visited, A:active { text-decoration: underline }
fonctionnalities
xmlInputMatchCallback
xmlOutputMatchCallback
for:
xmlSchemaGetCanonValue
+xmlXPathContextSetCache
forbid
XML_XPATH_NOVAR
force
xmlKeepBlanksDefault
xmlSetGenericErrorFunc
@@ -320,6 +321,7 @@ A:link, A:visited, A:active { text-decoration: underline }
freeing
xmlCanonicPath
xmlParserInputDeallocate
frees
xmlBufferFree
+xmlXPathContextSetCache
front
xmlValidateNCName
xmlValidateNMToken
xmlValidateName
diff --git a/doc/APIchunk17.html b/doc/APIchunk17.html index 892cf52..071403e 100644 --- a/doc/APIchunk17.html +++ b/doc/APIchunk17.html @@ -464,6 +464,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlRelaxNGNewDocParserCtxt
xmlRemoveID
xmlRemoveRef
+xmlXPathContextSetCache
interned
xmlPatterncompile
xmlTextReaderConstString
interning
xmlCopyNodeList
diff --git a/doc/APIchunk19.html b/doc/APIchunk19.html index 0cde864..8541fe1 100644 --- a/doc/APIchunk19.html +++ b/doc/APIchunk19.html @@ -148,6 +148,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlExpMaxToken
xmlExpNewCtxt
xmlPatternMaxDepth
+xmlXPathContextSetCache
maybe
_xmlSchemaElement
mean
xmlPatternMinDepth
means
xmlExpNewRange
@@ -238,6 +239,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlPatternMinDepth
minus
xmlXPathStringFunction
minute
ftpListCallback
+
misc
xmlXPathContextSetCache
misleading
xmlParsePEReference
xmlParserHandlePEReference
mixed
XML_SCHEMAS_TYPE_MIXED
diff --git a/doc/APIchunk21.html b/doc/APIchunk21.html index 8817d3c..f503ffe 100644 --- a/doc/APIchunk21.html +++ b/doc/APIchunk21.html @@ -39,7 +39,9 @@ A:link, A:visited, A:active { text-decoration: underline } y-z

Letter o:

object?
xmlXPathNumberFunction
xmlXPathStringFunction
-
objects
xmlXPathCompareValues
+
objects
_xmlXPathContext
+xmlXPathCompareValues
+xmlXPathContextSetCache
xmlXPathDivValues
xmlXPathEqualValues
xmlXPathFreeNodeSetList
@@ -236,6 +238,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlSaveToFilename
xmlSaveToIO
xmlTextReaderSchemaValidateCtxt
+xmlXPathContextSetCache
ordered
xmlListAppend
xmlListInsert
xmlXPathNextAncestor
diff --git a/doc/APIchunk22.html b/doc/APIchunk22.html index dec8350..f4c8321 100644 --- a/doc/APIchunk22.html +++ b/doc/APIchunk22.html @@ -146,6 +146,7 @@ A:link, A:visited, A:active { text-decoration: underline }
per
xmlGetLastError
xmlParseAttributeType
xmlValidateElementDecl
+xmlXPathContextSetCache
performance
xmlGetBufferAllocationScheme
xmlSetBufferAllocationScheme
performed
htmlNodeStatus
diff --git a/doc/APIchunk23.html b/doc/APIchunk23.html index ebbea9a..4a78224 100644 --- a/doc/APIchunk23.html +++ b/doc/APIchunk23.html @@ -541,9 +541,11 @@ A:link, A:visited, A:active { text-decoration: underline } xmlHashUpdateEntry3
retry
xmlValidGetValidElements
returning
xmlXPathStringFunction
+
reusal
_xmlXPathContext
reuse
xmlReconciliateNs
xmlRegExecPushString
xmlRegExecPushString2
+
reused
xmlXPathContextSetCache
reuses
htmlCtxtReadDoc
htmlCtxtReadFd
htmlCtxtReadFile
diff --git a/doc/APIchunk24.html b/doc/APIchunk24.html index fa596f6..6ac493b 100644 --- a/doc/APIchunk24.html +++ b/doc/APIchunk24.html @@ -180,6 +180,7 @@ A:link, A:visited, A:active { text-decoration: underline }
self
xmlXPathNextSelf
semantic
xmlAutomataNewNegTrans
xmlXPathNodeSetFreeNs
+
semantics
xmlXPathContextSetCache
sense
xmlCreateEntitiesTable
separated
xmlLoadCatalogs
separately
xmlSetGenericErrorFunc
@@ -261,6 +262,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlXPathDifference
xmlXPathIntersection
setting
xmlSetGenericErrorFunc
+xmlXPathContextSetCache
setups
xmlParseEncodingDecl
sgmlsource
getSystemId
xmlSAX2GetSystemId
@@ -388,6 +390,8 @@ A:link, A:visited, A:active { text-decoration: underline }
skipped
xmlParseElementChildrenContentDecl
xmlParseElementMixedContentDecl
xmlSkipBlankChars
+
slot
xmlXPathContextSetCache
+
slots
xmlXPathContextSetCache
smallest
xmlXPathCeilingFunction
socket
xmlCheckFilename
xmlNanoFTPGetSocket
@@ -797,6 +801,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlHashUpdateEntry3
xmlSchemaValueAppend
xmlXPathCompareValues
+xmlXPathContextSetCache
succeeds
xmlCheckFilename
xmlNewTextWriterPushParser
successful
xmlACatalogAdd
diff --git a/doc/APIchunk28.html b/doc/APIchunk28.html index 34ddc87..b5471fb 100644 --- a/doc/APIchunk28.html +++ b/doc/APIchunk28.html @@ -457,6 +457,7 @@ A:link, A:visited, A:active { text-decoration: underline }
xmlXPathFunction
xmlXPathFunctionLookup
xmlXPathFunctionLookupNS
xmlXPathNodeTrailingSorted
xmlXPathNodeTrailing
+
xmlXPathObject
xmlXPathContextSetCache
xmlXPathObjectPtr
xmlXPathCompiledEval
xmlXPathEval
xmlXPathEvalExpression
diff --git a/doc/APIchunk5.html b/doc/APIchunk5.html index dbc12b1..3ebc5a8 100644 --- a/doc/APIchunk5.html +++ b/doc/APIchunk5.html @@ -71,6 +71,7 @@ A:link, A:visited, A:active { text-decoration: underline }
Optional
_htmlElemDesc
Oriya
xmlUCSIsOriya
Osmanya
xmlUCSIsOsmanya
+
Other
xmlXPathContextSetCache
Otherwise
xmlStreamPush
xmlStreamPushAttr
Output
xmlOutputCloseCallback
diff --git a/doc/APIchunk8.html b/doc/APIchunk8.html index 87c07a4..82de64b 100644 --- a/doc/APIchunk8.html +++ b/doc/APIchunk8.html @@ -114,6 +114,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlParseMarkupDecl
Then
xmlValidateOneElement
There
xmlExpParse
+xmlXPathContextSetCache
Those
_xmlParserCtxt
Thus:
xmlXPathSubstringFunction
Tibetan
xmlUCSIsTibetan
@@ -249,6 +250,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlTextReaderSchemaValidate
xmlTextReaderSchemaValidateCtxt
xmlTextReaderSetSchema
+xmlXPathContextSetCache
Used
XML_SCHEMAS_ANY_LAX
XML_SCHEMAS_ANY_STRICT
XML_SCHEMAS_ATTR_USE_PROHIBITED
diff --git a/doc/APIfiles.html b/doc/APIfiles.html index 2de70cc..2a5af4b 100644 --- a/doc/APIfiles.html +++ b/doc/APIfiles.html @@ -2457,6 +2457,7 @@ A:link, A:visited, A:active { text-decoration: underline } XML_SCHEMAV_INVALIDATTR
XML_SCHEMAV_INVALIDELEM
XML_SCHEMAV_ISABSTRACT
+XML_SCHEMAV_MISC
XML_SCHEMAV_MISSING
XML_SCHEMAV_NOROLLBACK
XML_SCHEMAV_NOROOT
@@ -3274,6 +3275,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlXPathCompiledEval
xmlXPathContext
xmlXPathContextPtr
+xmlXPathContextSetCache
xmlXPathConvertBoolean
xmlXPathConvertFunc
xmlXPathConvertNumber
diff --git a/doc/APIfunctions.html b/doc/APIfunctions.html index 042bc3a..92489fb 100644 --- a/doc/APIfunctions.html +++ b/doc/APIfunctions.html @@ -2164,6 +2164,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlXPathDebugDumpCompExpr
xmlXPathFreeCompExpr

Type xmlXPathContextPtr:

xmlXPathCompiledEval
+xmlXPathContextSetCache
xmlXPathCtxtCompile
xmlXPathEval
xmlXPathEvalExpression
diff --git a/doc/APIsymbols.html b/doc/APIsymbols.html index cc7019a..7e1ba3c 100644 --- a/doc/APIsymbols.html +++ b/doc/APIsymbols.html @@ -1199,6 +1199,7 @@ A:link, A:visited, A:active { text-decoration: underline } XML_SCHEMAV_INVALIDATTR
XML_SCHEMAV_INVALIDELEM
XML_SCHEMAV_ISABSTRACT
+XML_SCHEMAV_MISC
XML_SCHEMAV_MISSING
XML_SCHEMAV_NOROLLBACK
XML_SCHEMAV_NOROOT
@@ -3292,6 +3293,7 @@ A:link, A:visited, A:active { text-decoration: underline } xmlXPathContainsFunction
xmlXPathContext
xmlXPathContextPtr
+xmlXPathContextSetCache
xmlXPathConvertBoolean
xmlXPathConvertFunc
xmlXPathConvertNumber
diff --git a/doc/DOM.html b/doc/DOM.html index 52f1139..a637399 100644 --- a/doc/DOM.html +++ b/doc/DOM.html @@ -7,11 +7,11 @@ H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } -DOM Principles
Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
Made with Libxml2 Logo

The XML C parser and toolkit of Gnome

DOM Principles

Developer Menu
API Indexes
Related links

DOM stands for the Document -Object Model; this is an API for accessing XML or HTML structured -documents. Native support for DOM in Gnome is on the way (module gnome-dom), -and will be based on gnome-xml. This will be a far cleaner interface to -manipulate XML files within Gnome since it won't expose the internal -structure.

The current DOM implementation on top of libxml2 is the gdome2 Gnome module, this -is a full DOM interface, thanks to Paolo Casarini, check the Gdome2 homepage for more -informations.

Daniel Veillard

+DOM Principles
Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
Made with Libxml2 Logo

The XML C parser and toolkit of Gnome

DOM Principles

Developer Menu
API Indexes
Related links

DOMstands for the +DocumentObjectModel; this is an API for accessing XML or HTML +structureddocuments.Native support for DOM in Gnome is on the way (module +gnome-dom),and will bebased on gnome-xml. This will be a far cleaner +interface tomanipulate XMLfiles within Gnome since it won't expose the +internalstructure.

The current DOM implementation on top of libxml2 is the gdome2 Gnome module,thisis +a full DOM interface, thanks to Paolo Casarini, check the Gdome2 +homepageformoreinformations.

Daniel Veillard

diff --git a/doc/FAQ.html b/doc/FAQ.html index 0d5ded6..cdc6585 100644 --- a/doc/FAQ.html +++ b/doc/FAQ.html @@ -12,53 +12,49 @@ A:link, A:visited, A:active { text-decoration: underline }

  • Compilation
  • Developer corner

    • License(s)

    1. Licensing Terms for libxml -

      libxml2 is released under the MIT - License; see the file Copyright in the distribution for the precise - wording

      +

      libxml2 is released under the MITLicense;see + the file Copyright in the distribution for the precisewording

    2. Can I embed libxml2 in a proprietary application ? -

      Yes. The MIT License allows you to keep proprietary the changes you - made to libxml, but it would be graceful to send-back bug fixes and - improvements as patches for possible incorporation in the main - development tree.

      +

      Yes. The MIT License allows you to keep proprietary the changesyoumade + to libxml, but it would be graceful to send-back bug fixesandimprovements + as patches for possible incorporation in themaindevelopment tree.

      3. -

    Installation

    1. Do Not Use - libxml1, use libxml2
      2. -
    2. Where can I get libxml ? -

      The original distribution comes from xmlsoft.org or gnome.org

      -

      Most Linux and BSD distributions include libxml, this is probably the - safer way for end-users to use libxml.

      +

    Installation

    1. Do + NotUselibxml1, use libxml2
      2. +
    2. Where can I get libxml? +

      The original distribution comes from xmlsoft.orgor gnome.org

      +

      Most Linux and BSD distributions include libxml, this is + probablythesafer way for end-users to use libxml.

      David Doolin provides precompiled Windows versions at http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/

    3. I see libxml and libxml2 releases, which one should I install ? -
      • If you are not constrained by backward compatibility issues with - existing applications, install libxml2 only
        • -
      • If you are not doing development, you can safely install both. - Usually the packages libxml and libxml2 are - compatible (this is not the case for development packages).
        • -
      • If you are a developer and your system provides separate packaging - for shared libraries and the development components, it is possible - to install libxml and libxml2, and also libxml-devel - and libxml2-devel - too for libxml2 >= 2.3.0
        • -
      • If you are developing a new application, please develop against - libxml2(-devel)
        • +
        • If you are not constrained by backward compatibility + issueswithexisting applications, install libxml2 only
          • +
        • If you are not doing development, you can safely + installboth.Usually the packages libxmland libxml2arecompatible(this + is not the case for development packages).
          • +
        • If you are a developer and your system provides + separatepackagingfor shared libraries and the development components, + it ispossibleto install libxml and libxml2, and also libxml-develandlibxml2-develtoofor + libxml2 >= 2.3.0
          • +
        • If you are developing a new application, please + developagainstlibxml2(-devel)
      • I can't install the libxml package, it conflicts with libxml0 -

        You probably have an old libxml0 package used to provide the shared - library for libxml.so.0, you can probably safely remove it. The libxml - packages provided on xmlsoft.org provide - libxml.so.0

        +

        You probably have an old libxml0 package used to provide + thesharedlibrary for libxml.so.0, you can probably safely remove it. + Thelibxmlpackages provided on xmlsoft.orgprovidelibxml.so.0

        • -
      • I can't install the libxml(2) RPM package due to failed - dependencies -

        The most generic solution is to re-fetch the latest src.rpm , and - rebuild it locally with

        +
      • I can't install the libxml(2) RPM package due + tofaileddependencies +

        The most generic solution is to re-fetch the latest src.rpm + ,andrebuild it locally with

        rpm --rebuild libxml(2)-xxx.src.rpm.

        -

        If everything goes well it will generate two binary rpm packages (one - providing the shared libs and xmllint, and the other one, the -devel - package, providing includes, static libraries and scripts needed to build - applications with libxml(2)) that you can install locally.

        +

        If everything goes well it will generate two binary rpm + packages(oneproviding the shared libs and xmllint, and the other one, + the-develpackage, providing includes, static libraries and scripts needed + tobuildapplications with libxml(2)) that you can install locally.

    Compilation

    1. What is the process to compile libxml2 ?

      As most UNIX libraries libxml2 follows the "standard":

      @@ -69,109 +65,106 @@ A:link, A:visited, A:active { text-decoration: underline }

      ./configure [possible options]

      make

      make install

      -

      At that point you may have to rerun ldconfig or a similar utility to - update your list of installed shared libs.

      +

      At that point you may have to rerun ldconfig or a similar + utilitytoupdate your list of installed shared libs.

    2. What other libraries are needed to compile/install libxml2 ? -

      Libxml2 does not require any other library, the normal C ANSI API - should be sufficient (please report any violation to this rule you may - find).

      -

      However if found at configuration time libxml2 will detect and use the - following libs:

      -
      • libz : a - highly portable and available widely compression library.
        • -
      • iconv: a powerful character encoding conversion library. It is - included by default in recent glibc libraries, so it doesn't need to - be installed specifically on Linux. It now seems a part - of the official UNIX specification. Here is one implementation of the - library which source can be found here.
        • +

        Libxml2 does not require any other library, the normal C ANSIAPIshould + be sufficient (please report any violation to this rule youmayfind).

        +

        However if found at configuration time libxml2 will detect and + usethefollowing libs:

        +
        • libz:ahighly + portable and available widely compression library.
          • +
        • iconv: a powerful character encoding conversion library. + Itisincluded by default in recent glibc libraries, so it doesn't + needtobe installed specifically on Linux. It now seems a partofthe + official UNIXspecification. Here is one implementation + ofthelibrarywhich source can be found here.
      • Make check fails on some platforms -

        Sometimes the regression tests' results don't completely match the - value produced by the parser, and the makefile uses diff to print the - delta. On some platforms the diff return breaks the compilation process; - if the diff is small this is probably not a serious problem.

        -

        Sometimes (especially on Solaris) make checks fail due to limitations - in make. Try using GNU-make instead.

        +

        Sometimes the regression tests' results don't completely matchthevalue + produced by the parser, and the makefile uses diff to printthedelta. On + some platforms the diff return breaks the compilationprocess;if the diff + is small this is probably not a serious problem.

        +

        Sometimes (especially on Solaris) make checks fail due tolimitationsin + make. Try using GNU-make instead.

      • I use the CVS version and there is no configure script -

        The configure script (and other Makefiles) are generated. Use the - autogen.sh script to regenerate the configure script and Makefiles, - like:

        +

        The configure script (and other Makefiles) are generated. + Usetheautogen.sh script to regenerate the configure script + andMakefiles,like:

        ./autogen.sh --prefix=/usr --disable-shared

      • I have troubles when running make tests with gcc-3.0 -

        It seems the initial release of gcc-3.0 has a problem with the - optimizer which miscompiles the URI module. Please use another - compiler.

        +

        It seems the initial release of gcc-3.0 has a problem withtheoptimizer + which miscompiles the URI module. Please useanothercompiler.

        • -

    Developer corner

    1. Troubles compiling or linking programs using libxml2 -

      Usually the problem comes from the fact that the compiler doesn't get - the right compilation or linking flags. There is a small shell script - xml2-config which is installed as part of libxml2 usual - install process which provides those flags. Use

      +

    Developercorner

    1. Troubles compiling or linking programs using libxml2 +

      Usually the problem comes from the fact that the compiler + doesn'tgetthe right compilation or linking flags. There is a small + shellscriptxml2-configwhich is installed as part of + libxml2usualinstall process which provides those flags. Use

      xml2-config --cflags

      to get the compilation flags and

      xml2-config --libs

      -

      to get the linker flags. Usually this is done directly from the - Makefile as:

      +

      to get the linker flags. Usually this is done directly fromtheMakefile + as:

      CFLAGS=`xml2-config --cflags`

      LIBS=`xml2-config --libs`

      2. -
    2. I want to install my own copy of libxml2 in my home directory and - link my programs against it, but it doesn't work -

      There are many different ways to accomplish this. Here is one way to - do this under Linux. Suppose your home directory is /home/user. - Then:

      +
    3. I want to install my own copy of libxml2 in my home + directoryandlink my programs against it, but it doesn't work +

      There are many different ways to accomplish this. Here is one waytodo + this under Linux. Suppose your home directory + is/home/user.Then:

      • Create a subdirectory, let's call it myxml
      • unpack the libxml2 distribution into that subdirectory
        • -
      • chdir into the unpacked distribution - (/home/user/myxml/libxml2 )
        • -
      • configure the library using the "--prefix" switch, - specifying an installation subdirectory in - /home/user/myxml, e.g. -

        ./configure --prefix /home/user/myxml/xmlinst {other - configuration options}

        +
      • chdir into the unpacked + distribution(/home/user/myxml/libxml2)
        • +
      • configure the library using the + "--prefix"switch,specifying an installation + subdirectoryin/home/user/myxml, e.g. +

        ./configure + --prefix/home/user/myxml/xmlinst{otherconfiguration + options}

        • -
      • now run make followed by make install
        • -
      • At this point, the installation subdirectory contains the complete - "private" include files, library files and binary program files (e.g. - xmllint), located in -

        /home/user/myxml/xmlinst/lib, - /home/user/myxml/xmlinst/include and - /home/user/myxml/xmlinst/bin

        +
      • now run makefollowed by make install
        • +
      • At this point, the installation subdirectory contains + thecomplete"private" include files, library files and binary + programfiles (e.g.xmllint), located in +

        /home/user/myxml/xmlinst/lib,/home/user/myxml/xmlinst/includeand + /home/user/myxml/xmlinst/bin

        respectively.
        • -
      • In order to use this "private" library, you should first add it to - the beginning of your default PATH (so that your own private program - files such as xmllint will be used instead of the normal system - ones). To do this, the Bash command would be +
      • In order to use this "private" library, you should first add + ittothe beginning of your default PATH (so that your own + privateprogramfiles such as xmllint will be used instead of the + normalsystemones). To do this, the Bash command would be

        export PATH=/home/user/myxml/xmlinst/bin:$PATH

        • -
      • Now suppose you have a program test1.c that you would - like to compile with your "private" library. Simply compile it using - the command +
      • Now suppose you have a program test1.cthat + youwouldlike to compile with your "private" library. Simply compile + itusingthe command

        gcc `xml2-config --cflags --libs` -o test test.c

        - Note that, because your PATH has been set with - /home/user/myxml/xmlinst/bin at the beginning, the xml2-config - program which you just installed will be used instead of the system - default one, and this will automatically get the correct - libraries linked with your program.
        • + Note that, because your PATH has been set + with/home/user/myxml/xmlinst/binat the beginning, + thexml2-configprogram which you just installed will be used instead + ofthe systemdefault one, and this will automaticallyget + thecorrectlibraries linked with your program.

    4. xmlDocDump() generates output on one line. -

      Libxml2 will not invent spaces in the content of a - document since all spaces in the content of a document are - significant. If you build a tree from the API and want - indentation:

      +

      Libxml2 will not inventspaces in the content + ofadocument since all spaces in the content of a + documentaresignificant. If you build a tree from the API + andwantindentation:

      1. the correct way is to generate those yourself too.
        2. -
      2. the dangerous way is to ask libxml2 to add those blanks to your - content modifying the content of your document in the - process. The result may not be what you expect. There is - NO way to guarantee that such a modification won't - affect other parts of the content of your document. See xmlKeepBlanksDefault - () and xmlSaveFormatFile - ()
        3. +
      3. the dangerous way is to ask libxml2 to add those blanks + toyourcontent modifying the content of your document + intheprocess. The result may not be what you expect. + ThereisNOway to guarantee that such a + modificationwon'taffect other parts of the content of your document. + See xmlKeepBlanksDefault()andxmlSaveFormatFile()
    5. Extra nodes in the document:

      For a XML file as below:

      @@ -180,10 +173,10 @@ A:link, A:visited, A:active { text-decoration: underline } <NODE CommFlag="0"/> <NODE CommFlag="1"/> </PLAN> -

      after parsing it with the function - pxmlDoc=xmlParseFile(...);

      -

      I want to the get the content of the first node (node with the - CommFlag="0")

      +

      after parsing it with + thefunctionpxmlDoc=xmlParseFile(...);

      +

      I want to the get the content of the first node (node + withtheCommFlag="0")

      so I did it as following;

      xmlNodePtr pnode;
 pnode=pxmlDoc->children->children;
      @@ -191,63 +184,62 @@ pnode=pxmlDoc->children->children; 
      pnode=pxmlDoc->children->children->next;

      then it works. Can someone explain it to me.

      -

      In XML all characters in the content of the document are significant - including blanks and formatting line breaks.

      -

      The extra nodes you are wondering about are just that, text nodes with - the formatting spaces which are part of the document but that people tend - to forget. There is a function xmlKeepBlanksDefault - () to remove those at parse time, but that's an heuristic, and its - use should be limited to cases where you are certain there is no - mixed-content in the document.

      +

      In XML all characters in the content of the document + aresignificantincluding blanks and formatting + linebreaks.

      +

      The extra nodes you are wondering about are just that, text + nodeswiththe formatting spaces which are part of the document but that + peopletendto forget. There is a function xmlKeepBlanksDefault()toremove + those at parse time, but that's an heuristic, and itsuse should belimited + to cases where you are certain there is nomixed-content in + thedocument.

      6. -
    6. I get compilation errors of existing code like when accessing - root or child fields of nodes. -

      You are compiling code developed for libxml version 1 and using a - libxml2 development environment. Either switch back to libxml v1 devel or - even better fix the code to compile with libxml2 (or both) by following the instructions.

      +
    7. I get compilation errors of existing code like + whenaccessingrootor child + fieldsofnodes. +

      You are compiling code developed for libxml version 1 and + usingalibxml2 development environment. Either switch back to libxml v1 + develoreven better fix the code to compile with libxml2 (or both) by following the instructions.

      8. -
    8. I get compilation errors about non existing - xmlRootNode or xmlChildrenNode - fields. -

      The source code you are using has been upgraded to be able to compile with both libxml - and libxml2, but you need to install a more recent version: - libxml(-devel) >= 1.8.8 or libxml2(-devel) >= 2.1.0

      +
    9. I get compilation errors about + nonexistingxmlRootNodeorxmlChildrenNodefields. +

      The source code you are using has been upgradedto be able to compile with both + libxmlandlibxml2, but you need to install a more recent + version:libxml(-devel)>= 1.8.8 or libxml2(-devel) >= 2.1.0

    10. XPath implementation looks seriously broken -

      XPath implementation prior to 2.3.0 was really incomplete. Upgrade to - a recent version, there are no known bugs in the current version.

      +

      XPath implementation prior to 2.3.0 was really incomplete. Upgrade + toarecent version, there are no known bugs in the current version.

    11. The example provided in the web page does not compile. -

      It's hard to maintain the documentation in sync with the code - <grin/> ...

      -

      Check the previous points 1/ and 2/ raised before, and please send - patches.

      +

      It's hard to maintain the documentation in sync with + thecode<grin/> ...

      +

      Check the previous points 1/ and 2/ raised before, and + pleasesendpatches.

      12. -
    12. Where can I get more examples and information than provided on the - web page? -

      Ideally a libxml2 book would be nice. I have no such plan ... But you - can:

      -
      • check more deeply the existing - generated doc
        • -
      • have a look at the set of - examples.
        • -
      • look for examples of use for libxml2 function using the Gnome code. - For example the following will query the full Gnome CVS base for the - use of the xmlAddChild() function: +
      • Where can I get more examples and information than provided + ontheweb page? +

        Ideally a libxml2 book would be nice. I have no such plan ... + Butyoucan:

        +
        • check more deeply the existinggenerated doc
          • +
        • have a look at the + setofexamples.
          • +
        • look for examples of use for libxml2 function using the + Gnomecode.For example the following will query the full Gnome CVS + base fortheuse of the xmlAddChild()function:

          http://cvs.gnome.org/lxr/search?string=xmlAddChild

          -

          This may be slow, a large hardware donation to the gnome project - could cure this :-)

          +

          This may be slow, a large hardware donation to the + gnomeprojectcould cure this :-)

          • -
        • Browse - the libxml2 source , I try to write code as clean and documented - as possible, so looking at it may be helpful. In particular the code - of xmllint.c and of the various testXXX.c test programs should - provide good examples of how to do things with the library.
          • +
        • Browsethelibxml2 + source, I try to write code as clean and documentedaspossible, so + looking at it may be helpful. In particular the codeofxmllint.c and + of the various testXXX.c test programs shouldprovidegood examples of + how to do things with the library.
      • What about C++ ? -

        libxml2 is written in pure C in order to allow easy reuse on a number - of platforms, including embedded systems. I don't intend to convert to - C++.

        +

        libxml2 is written in pure C in order to allow easy reuse on anumberof + platforms, including embedded systems. I don't intend to converttoC++.

        There is however a C++ wrapper which may fulfill your needs:

      • How to validate a document a posteriori ? -

        It is possible to validate documents which had not been validated at - initial parsing time or documents which have been built from scratch - using the API. Use the xmlValidateDtd() - function. It is also possible to simply add a DTD to an existing - document:

        +

        It is possible to validate documents which had not been + validatedatinitial parsing time or documents which have been built + fromscratchusing the API. Use the xmlValidateDtd()function.It + is also possible to simply add a DTD to an existingdocument:

        xmlDocPtr doc; /* your existing document */
 xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
 
@@ -277,10 +268,10 @@ xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
      • So what is this funky "xmlChar" used all the time? -

        It is a null terminated sequence of utf-8 characters. And only utf-8! - You need to convert strings encoded in different ways to utf-8 before - passing them to the API. This can be accomplished with the iconv library - for instance.

        +

        It is a null terminated sequence of utf-8 characters. And + onlyutf-8!You need to convert strings encoded in different ways to + utf-8beforepassing them to the API. This can be accomplished with the + iconvlibraryfor instance.

      • etc ...

    Daniel Veillard

    diff --git a/doc/XMLinfo.html b/doc/XMLinfo.html index 474f9c1..5314fac 100644 --- a/doc/XMLinfo.html +++ b/doc/XMLinfo.html @@ -7,9 +7,9 @@ H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } -XML
    Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
    Made with Libxml2 Logo

    The XML C parser and toolkit of Gnome

    XML

    Main Menu
    Related links

    XML is a standard for -markup-based structured documents. Here is an example XML -document:

    <?xml version="1.0"?>
+XML
    Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
    Made with Libxml2 Logo
    The XML C parser and toolkit of Gnome
    XML
    Main Menu
    Related links
    XML is astandardformarkup-based
+structured documents. Here is an example
+XMLdocument:
    <?xml version="1.0"?>
 <EXAMPLE prop1="gnome is great" prop2="&amp; linux too">
   <head>
    <title>Welcome to Gnome</title>
@@ -20,16 +20,17 @@ document:
    <?xml version="1.0"?>
    <image href="linus.gif"/>
    <p>...</p>
   </chapter>
-</EXAMPLE>
    The first line specifies that it is an XML document and gives useful
-information about its encoding.  Then the rest of the document is a text
-format whose structure is specified by tags between brackets. Each
-tag opened has to be closed. XML is pedantic about this. However, if
-a tag is empty (no content), a single tag can serve as both the opening and
-closing tag if it ends with /> rather than with
->. Note that, for example, the image tag has no content (just
-an attribute) and is closed by ending the tag with />.
    XML can be applied successfully to a wide range of tasks, ranging from
-long term structured document maintenance (where it follows the steps of
-SGML) to simple data encoding mechanisms like configuration file formatting
-(glade), spreadsheets (gnumeric), or even shorter lived documents such as
-WebDAV where it is used to encode remote calls between a client and a
-server.
    Daniel Veillard
    
+</EXAMPLE>

    The first line specifies that it is an XML document and +givesusefulinformation about its encoding. Then the rest of the document is +atextformat whose structure is specified by tags between +brackets.Eachtag opened has to be closed. XML is pedantic +about this.However, ifa tag is empty (no content), a single tag can serve as +both theopening andclosing tag if it ends with />rather +thanwith>. Note that, for example, the image tag has no +content(justan attribute) and is closed by ending the tag +with/>.

    XML can be applied successfully to a wide range of tasks, ranging +fromlongterm structured document maintenance (where it follows the steps +ofSGML) tosimple data encoding mechanisms like configuration file +formatting(glade),spreadsheets (gnumeric), or even shorter lived documents +such asWebDAV whereit is used to encode remote calls between a client and +aserver.

    Daniel Veillard

    diff --git a/doc/XSLT.html b/doc/XSLT.html index 657ead3..4a8c09b 100644 --- a/doc/XSLT.html +++ b/doc/XSLT.html @@ -7,7 +7,8 @@ H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } -XSLT
    Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
    Made with Libxml2 Logo

    The XML C parser and toolkit of Gnome

    XSLT

    Main Menu
    Related links

    Check the separate libxslt page

    XSL Transformations, is a -language for transforming XML documents into other XML documents (or -HTML/textual output).

    A separate library called libxslt is available implementing XSLT-1.0 for -libxml2. This module "libxslt" too can be found in the Gnome CVS base.

    You can check the progresses on the libxslt Changelog.

    Daniel Veillard

    +XSLT
    Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
    Made with Libxml2 Logo

    The XML C parser and toolkit of Gnome

    XSLT

    Main Menu
    Related links

    Check the separate libxslt page

    XSL Transformations, is +alanguagefor transforming XML documents into other XML documents +(orHTML/textualoutput).

    A separate library called libxslt is available implementing +XSLT-1.0forlibxml2. This module "libxslt" too can be found in the Gnome CVS +base.

    You can check the progresses on the libxslt Changelog.

    Daniel Veillard

    diff --git a/doc/architecture.html b/doc/architecture.html index 906c5b2..7809bc6 100644 --- a/doc/architecture.html +++ b/doc/architecture.html @@ -7,8 +7,8 @@ H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } -libxml2 architecture
    Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
    Made with Libxml2 Logo

    The XML C parser and toolkit of Gnome

    libxml2 architecture

    Developer Menu
    API Indexes
    Related links

    Libxml2 is made of multiple components; some of them are optional, and -most of the block interfaces are public. The main components are:

    • an Input/Output layer
      • +libxml2 architecture
      Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
      Made with Libxml2 Logo

      The XML C parser and toolkit of Gnome

      libxml2 architecture

      Developer Menu
      API Indexes
      Related links

      Libxml2 is made of multiple components; some of them are optional, +andmostof the block interfaces are public. The main components are:

      • an Input/Output layer
      • FTP and HTTP client layers (optional)
      • an Internationalization layer managing the encodings support
      • a URI module
        • @@ -17,7 +17,6 @@ most of the block interfaces are public. The main components are:

        • an
        • a SAX tree module to build an in-memory DOM representation
        • a tree module to manipulate the DOM representation
        • a validation module using the DOM representation (optional)
          • -
        • an XPath module for global lookup in a DOM representation - (optional)
          • +
        • an XPath module for global lookup in a DOM representation(optional)
        • a debug module (optional)

        Graphically this gives the following:

        a graphical view of the various

        Daniel Veillard

      diff --git a/doc/bugs.html b/doc/bugs.html index 6415c85..c755d00 100644 --- a/doc/bugs.html +++ b/doc/bugs.html @@ -7,62 +7,62 @@ H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } -Reporting bugs and getting help
      Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
      Made with Libxml2 Logo

      The XML C parser and toolkit of Gnome

      Reporting bugs and getting help

      Main Menu
      Related links

      Well, bugs or missing features are always possible, and I will make a -point of fixing them in a timely fashion. The best way to report a bug is to -use the Gnome -bug tracking database (make sure to use the "libxml2" module name). I -look at reports there regularly and it's good to have a reminder when a bug -is still open. Be sure to specify that the bug is for the package libxml2.

      For small problems you can try to get help on IRC, the #xml channel on -irc.gnome.org (port 6667) usually have a few person subscribed which may help -(but there is no garantee and if a real issue is raised it should go on the -mailing-list for archival).

      There is also a mailing-list xml@gnome.org for libxml, with an on-line archive (old). To subscribe to this list, -please visit the associated Web page and -follow the instructions. Do not send code, I won't debug it -(but patches are really appreciated!).

      Please note that with the current amount of virus and SPAM, sending mail -to the list without being subscribed won't work. There is *far too many -bounces* (in the order of a thousand a day !) I cannot approve them manually -anymore. If your mail to the list bounced waiting for administrator approval, -it is LOST ! Repost it and fix the problem triggering the error. Also please -note that emails with -a legal warning asking to not copy or redistribute freely the informations -they contain are NOT acceptable for the mailing-list, -such mail will as much as possible be discarded automatically, and are less -likely to be answered if they made it to the list, DO NOT -post to the list from an email address where such legal requirements are -automatically added, get private paying support if you can't share -informations.

      Check the following before -posting:

      • Read the FAQ and use the - search engine to get information related to your problem.
        • -
      • Make sure you are using a recent - version, and that the problem still shows up in a recent version.
        • -
      • Check the list - archives to see if the problem was reported already. In this case - there is probably a fix available, similarly check the registered - open bugs.
        • -
      • Make sure you can reproduce the bug with xmllint or one of the test - programs found in source in the distribution.
        • -
      • Please send the command showing the error as well as the input (as an - attachment)
        • -

      Then send the bug with associated information to reproduce it to the xml@gnome.org list; if it's really libxml -related I will approve it. Please do not send mail to me directly, it makes -things really hard to track and in some cases I am not the best person to -answer a given question, ask on the list.

      To be really clear about support:

      • Support or help requests MUST be sent to - the list or on bugzilla in case of problems, so that the Question - and Answers can be shared publicly. Failing to do so carries the implicit - message "I want free support but I don't want to share the benefits with - others" and is not welcome. I will automatically Carbon-Copy the - xml@gnome.org mailing list for any technical reply made about libxml2 or - libxslt.
        • -
      • There is no garantee of support, if - your question remains unanswered after a week, repost it, making sure you - gave all the detail needed and the information requested.
        • -
      • Failing to provide information as requested or double checking first - for prior feedback also carries the implicit message "the time of the - library maintainers is less valuable than my time" and might not be - welcome.
        • -

      Of course, bugs reported with a suggested patch for fixing them will -probably be processed faster than those without.

      If you're looking for help, a quick look at the list archive may actually -provide the answer. I usually send source samples when answering libxml2 -usage questions. The auto-generated documentation is -not as polished as I would like (i need to learn more about DocBook), but -it's a good starting point.

      Daniel Veillard

      +Reporting bugs and getting help
      Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
      Made with Libxml2 Logo

      The XML C parser and toolkit of Gnome

      Reporting bugs and getting help

      Main Menu
      Related links

      Well, bugs or missing features are always possible, and I will make +apointof fixing them in a timely fashion. The best way to report a bug is +touse theGnomebugtracking +database(make sure to use the "libxml2" module name). Ilook atreports +there regularly and it's good to have a reminder when a bugis stillopen. Be +sure to specify that the bug is for the package libxml2.

      For small problems you can try to get help on IRC, the #xml +channelonirc.gnome.org (port 6667) usually have a few person subscribed which +mayhelp(but there is no garantee and if a real issue is raised it should go +onthemailing-list for archival).

      There is also a mailing-list xml@gnome.orgfor libxml, with an on-line archive(old). To subscribe to this +list,pleasevisit the associatedWebpage +andfollow the instructions. Do not send code, I won'tdebug +it(but patches are really appreciated!).

      Please note that with the current amount of virus and SPAM, sending +mailtothe list without being subscribed won't work. There is *far too +manybounces*(in the order of a thousand a day !) I cannot approve them +manuallyanymore.If your mail to the list bounced waiting for administrator +approval,it isLOST ! Repost it and fix the problem triggering the error. Also +pleasenotethat emails +withalegal warning asking to not copy or redistribute freely the +informationstheycontainare NOTacceptable for the +mailing-list,suchmail will as much as possible be discarded automatically, +and are lesslikelyto be answered if they made it to the list, DO +NOTpost tothe list from an email address where such legal +requirements areautomaticallyadded, get private paying support if you can't +shareinformations.

      Check the following beforeposting:

      • Read the FAQand usethesearch engineto get information related to + your problem.
        • +
      • Make sure you are using + arecentversion, and that the problem still shows up in a + recentversion.
        • +
      • Check the listarchivesto see if + theproblem was reported already. In this casethere is probably a + fixavailable, similarly check the registeredopenbugs.
        • +
      • Make sure you can reproduce the bug with xmllint or one of + thetestprograms found in source in the distribution.
        • +
      • Please send the command showing the error as well as the input + (asanattachment)
        • +

      Then send the bug with associated information to reproduce it to the xml@gnome.orglist; if it's +reallylibxmlrelated I will approve it. Please do not send mail to me +directly, itmakesthings really hard to track and in some cases I am not the +best persontoanswer a given question, ask on the list.

      To be really clear about support:

      • Support or help requests MUST be senttothe + list or on bugzillain case of problems, so that theQuestionand + Answers can be shared publicly. Failing to do so carries + theimplicitmessage "I want free support but I don't want to share + thebenefits withothers" and is not welcome. I will automatically + Carbon-Copythexml@gnome.org mailing list for any technical reply made + about libxml2orlibxslt.
        • +
      • There is no garantee of + support,ifyour question remains unanswered after a week, repost + it, making sureyougave all the detail needed and the information + requested.
        • +
      • Failing to provide information as requested or double checking + firstforprior feedback also carries the implicit message "the time of + thelibrarymaintainers is less valuable than my time" and might not + bewelcome.
        • +

      Of course, bugs reported with a suggested patch for fixing +themwillprobably be processed faster than those without.

      If you're looking for help, a quick look at the list +archivemayactuallyprovide the answer. I usually send source samples when +answeringlibxml2usage questions. The auto-generateddocumentationisnot +as polished as I would like (i need to learn moreabout DocBook), butit's a +good starting point.

      Daniel Veillard

      diff --git a/doc/catalog.html b/doc/catalog.html index 4100fed..34f9902 100644 --- a/doc/catalog.html +++ b/doc/catalog.html @@ -14,77 +14,78 @@ A:link, A:visited, A:active { text-decoration: underline }
    • How to tune catalog usage
    • How to debug catalog processing
    • How to create and maintain catalogs
      • -
    • The implementor corner quick review of the - API
      • +
    • The implementor corner quick review + oftheAPI
    • Other resources
      • -

      General overview

      What is a catalog? Basically it's a lookup mechanism used when an entity -(a file or a remote resource) references another entity. The catalog lookup -is inserted between the moment the reference is recognized by the software -(XML parser, stylesheet processing, or even images referenced for inclusion -in a rendering) and the time where loading that resource is actually -started.

      It is basically used for 3 things:

      • mapping from "logical" names, the public identifiers and a more - concrete name usable for download (and URI). For example it can associate - the logical name +

        General overview

        What is a catalog? Basically it's a lookup mechanism used when an +entity(afile or a remote resource) references another entity. The catalog +lookupisinserted between the moment the reference is recognized by the +software(XMLparser, stylesheet processing, or even images referenced for +inclusionin arendering) and the time where loading that resource is +actuallystarted.

        It is basically used for 3 things:

        • mapping from "logical" names, the public identifiers and a + moreconcretename usable for download (and URI). For example it can + associatethelogical name

          "-//OASIS//DTD DocBook XML V4.1.2//EN"

          -

          of the DocBook 4.1.2 XML DTD with the actual URL where it can be - downloaded

          +

          of the DocBook 4.1.2 XML DTD with the actual URL where it + canbedownloaded

          http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd

          • -
        • remapping from a given URL to another one, like an HTTP indirection - saying that +
        • remapping from a given URL to another one, like an + HTTPindirectionsaying that

          "http://www.oasis-open.org/committes/tr.xsl"

          should really be looked at

          "http://www.oasis-open.org/committes/entity/stylesheets/base/tr.xsl"

          • -
        • providing a local cache mechanism allowing to load the entities - associated to public identifiers or remote resources, this is a really - important feature for any significant deployment of XML or SGML since it - allows to avoid the aleas and delays associated to fetching remote - resources.
          • -

        The definitions

        Libxml, as of 2.4.3 implements 2 kind of catalogs:

        • the older SGML catalogs, the official spec is SGML Open Technical - Resolution TR9401:1997, but is better understood by reading the SP Catalog page from - James Clark. This is relatively old and not the preferred mode of - operation of libxml.
          • -
        • XML - Catalogs is far more flexible, more recent, uses an XML syntax and - should scale quite better. This is the default option of libxml.
          • -

        Using catalog

        In a normal environment libxml2 will by default check the presence of a -catalog in /etc/xml/catalog, and assuming it has been correctly populated, -the processing is completely transparent to the document user. To take a -concrete example, suppose you are authoring a DocBook document, this one -starts with the following DOCTYPE definition:

        <?xml version='1.0'?>
+  
      • providing a local cache mechanism allowing to load
+    theentitiesassociated to public identifiers or remote resources, this is
+    areallyimportant feature for any significant deployment of XML or
+    SGMLsince itallows to avoid the aleas and delays associated to
+    fetchingremoteresources.
        • 
+

      The definitions

      Libxml, as of 2.4.3 implements 2 kind of catalogs:

      • the older SGML catalogs, the official spec is SGML + OpenTechnicalResolution TR9401:1997, but is better understood by reading + the SP + CatalogpagefromJames Clark. This is relatively old and not the + preferredmode ofoperation of libxml.
        • +
      • XMLCatalogsisfar + more flexible, more recent, uses an XML syntax andshould scale + quitebetter. This is the default option of libxml.
        • +

      Using catalog

      In a normal environment libxml2 will by default check the presence +ofacatalog in /etc/xml/catalog, and assuming it has been +correctlypopulated,the processing is completely transparent to the document +user. Totake aconcrete example, suppose you are authoring a DocBook document, +thisonestarts with the following DOCTYPE definition:

      <?xml version='1.0'?>
 <!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
-          "http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd">

      When validating the document with libxml, the catalog will be -automatically consulted to lookup the public identifier "-//Norman Walsh//DTD -DocBk XML V3.1.4//EN" and the system identifier -"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if these entities have -been installed on your system and the catalogs actually point to them, libxml -will fetch them from the local disk.

      Note: Really don't use this -DOCTYPE example it's a really old version, but is fine as an example.

      Libxml2 will check the catalog each time that it is requested to load an -entity, this includes DTD, external parsed entities, stylesheets, etc ... If -your system is correctly configured all the authoring phase and processing -should use only local files, even if your document stays portable because it -uses the canonical public and system ID, referencing the remote document.

      Some examples:

      Here is a couple of fragments from XML Catalogs used in libxml2 early -regression tests in test/catalogs :

      <?xml version="1.0"?>
+          "http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd">

      When validating the document with libxml, the catalog will +beautomaticallyconsulted to lookup the public identifier "-//Norman +Walsh//DTDDocBk XMLV3.1.4//EN" and the +systemidentifier"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if +theseentities havebeen installed on your system and the catalogs actually +point tothem, libxmlwill fetch them from the local disk.

      Note: Really don't usethisDOCTYPE +example it's a really old version, but is fine as an example.

      Libxml2 will check the catalog each time that it is requested to +loadanentity, this includes DTD, external parsed entities, stylesheets, etc +...Ifyour system is correctly configured all the authoring phase +andprocessingshould use only local files, even if your document stays +portablebecause ituses the canonical public and system ID, referencing the +remotedocument.

      Some examples:

      Here is a couple of fragments from XML Catalogs used in +libxml2earlyregression tests in test/catalogs:

      <?xml version="1.0"?>
 <!DOCTYPE catalog PUBLIC 
    "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
    "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
 <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
   <public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
    uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/>
-...

      This is the beginning of a catalog for DocBook 4.1.2, XML Catalogs are -written in XML, there is a specific namespace for catalog elements -"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry in this -catalog is a public mapping it allows to associate a Public -Identifier with an URI.

      ...
+...

      This is the beginning of a catalog for DocBook 4.1.2, XML +Catalogsarewritten in XML, there is a specific namespace for +catalogelements"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry +inthiscatalog is a publicmapping it allows to associate +aPublicIdentifier with an URI.

      ...
     <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/"
                    rewritePrefix="file:///usr/share/xml/docbook/"/>
-...

      A rewriteSystem is a very powerful instruction, it says that -any URI starting with a given prefix should be looked at another URI -constructed by replacing the prefix with an new one. In effect this acts like -a cache system for a full area of the Web. In practice it is extremely useful -with a file prefix if you have installed a copy of those resources on your -local system.

      ...
+...

      A rewriteSystemis a very powerful instruction, it saysthatany +URI starting with a given prefix should be looked at anotherURIconstructed by +replacing the prefix with an new one. In effect this actslikea cache system +for a full area of the Web. In practice it is extremelyusefulwith a file +prefix if you have installed a copy of those resources onyourlocal system.

      ...
 <delegatePublic publicIdStartString="-//OASIS//DTD XML Catalog //"
                 catalog="file:///usr/share/xml/docbook.xml"/>
 <delegatePublic publicIdStartString="-//OASIS//ENTITIES DocBook XML"
@@ -95,21 +96,21 @@ local system.
      ...
                 catalog="file:///usr/share/xml/docbook.xml"/>
 <delegateURI uriStartString="http://www.oasis-open.org/docbook/"
                 catalog="file:///usr/share/xml/docbook.xml"/>
-...
      Delegation is the core features which allows to build a tree of catalogs,
-easier to maintain than a single catalog, based on Public Identifier, System
-Identifier or URI prefixes it instructs the catalog software to look up
-entries in another resource. This feature allow to build hierarchies of
-catalogs, the set of entries presented should be sufficient to redirect the
-resolution of all DocBook references to the specific catalog in
-/usr/share/xml/docbook.xml this one in turn could delegate all
-references for DocBook 4.2.1 to a specific catalog installed at the same time
-as the DocBook resources on the local machine.
      How to tune catalog usage:
      The user can change the default catalog behaviour by redirecting queries
-to its own set of catalogs, this can be done by setting the
-XML_CATALOG_FILES environment variable to a list of catalogs, an
-empty one should deactivate loading the default /etc/xml/catalog
-default catalog
      How to debug catalog processing:
      Setting up the XML_DEBUG_CATALOG environment variable will
-make libxml2 output debugging informations for each catalog operations, for
-example:
      orchis:~/XML -> xmllint --memory --noout test/ent2
+...
      Delegation is the core features which allows to build a tree
+ofcatalogs,easier to maintain than a single catalog, based on
+PublicIdentifier, SystemIdentifier or URI prefixes it instructs the
+catalogsoftware to look upentries in another resource. This feature allow to
+buildhierarchies ofcatalogs, the set of entries presented should be
+sufficient toredirect theresolution of all DocBook references to the specific
+catalogin/usr/share/xml/docbook.xmlthis one in turn could
+delegateallreferences for DocBook 4.2.1 to a specific catalog installed at
+the sametimeas the DocBook resources on the local machine.
      How to tune catalog usage:
      The user can change the default catalog behaviour by redirecting
+queriestoits own set of catalogs, this can be done by
+settingtheXML_CATALOG_FILESenvironment variable to a list of
+catalogs,anempty one should deactivate loading the
+default/etc/xml/catalogdefault catalog
      How to debug catalog processing:
      Setting up the XML_DEBUG_CATALOGenvironment variable
+willmakelibxml2 output debugging informations for each catalog
+operations,forexample:
      orchis:~/XML -> xmllint --memory --noout test/ent2
 warning: failed to load external entity "title.xml"
 orchis:~/XML -> export XML_DEBUG_CATALOG=
 orchis:~/XML -> xmllint --memory --noout test/ent2
@@ -117,26 +118,26 @@ Failed to parse catalog /etc/xml/catalog
 Failed to parse catalog /etc/xml/catalog
 warning: failed to load external entity "title.xml"
 Catalogs cleanup
-orchis:~/XML -> 
      The test/ent2 references an entity, running the parser from memory makes
-the base URI unavailable and the the "title.xml" entity cannot be loaded.
-Setting up the debug environment variable allows to detect that an attempt is
-made to load the /etc/xml/catalog but since it's not present the
-resolution fails.
      But the most advanced way to debug XML catalog processing is to use the
-xmlcatalog command shipped with libxml2, it allows to load
-catalogs and make resolution queries to see what is going on. This is also
-used for the regression tests:
      orchis:~/XML -> ./xmlcatalog test/catalogs/docbook.xml \
+orchis:~/XML -> 
      The test/ent2 references an entity, running the parser from memorymakesthe
+base URI unavailable and the the "title.xml" entity cannot beloaded.Setting
+up the debug environment variable allows to detect that anattempt ismade to
+load the /etc/xml/catalogbut since it's notpresent theresolution
+fails.
      But the most advanced way to debug XML catalog processing is to
+usethexmlcatalogcommand shipped with libxml2, it allows
+toloadcatalogs and make resolution queries to see what is going on. This
+isalsoused for the regression tests:
      orchis:~/XML -> ./xmlcatalog test/catalogs/docbook.xml \
                    "-//OASIS//DTD DocBook XML V4.1.2//EN"
 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
-orchis:~/XML -> 
      For debugging what is going on, adding one -v flags increase the verbosity
-level to indicate the processing done (adding a second flag also indicate
-what elements are recognized at parsing):
      orchis:~/XML -> ./xmlcatalog -v test/catalogs/docbook.xml \
+orchis:~/XML -> 
      For debugging what is going on, adding one -v flags increase
+theverbositylevel to indicate the processing done (adding a second flag
+alsoindicatewhat elements are recognized at parsing):
      orchis:~/XML -> ./xmlcatalog -v test/catalogs/docbook.xml \
                    "-//OASIS//DTD DocBook XML V4.1.2//EN"
 Parsing catalog test/catalogs/docbook.xml's content
 Found public match -//OASIS//DTD DocBook XML V4.1.2//EN
 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
 Catalogs cleanup
-orchis:~/XML -> 
      A shell interface is also available to debug and process multiple queries
-(and for regression tests):
      orchis:~/XML -> ./xmlcatalog -shell test/catalogs/docbook.xml \
+orchis:~/XML -> 
      A shell interface is also available to debug and process
+multiplequeries(and for regression tests):
      orchis:~/XML -> ./xmlcatalog -shell test/catalogs/docbook.xml \
                    "-//OASIS//DTD DocBook XML V4.1.2//EN"
 > help   
 Commands available:
@@ -152,18 +153,18 @@ exit:  quit the shell
 > public "-//OASIS//DTD DocBook XML V4.1.2//EN"
 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
 > quit
-orchis:~/XML -> 
      This should be sufficient for most debugging purpose, this was actually
-used heavily to debug the XML Catalog implementation itself.
      How to create and maintain catalogs:
      Basically XML Catalogs are XML files, you can either use XML tools to
-manage them or use  xmlcatalog for this. The basic step is
-to create a catalog the -create option provide this facility:
      orchis:~/XML -> ./xmlcatalog --create tst.xml
+orchis:~/XML -> 
      This should be sufficient for most debugging purpose, this wasactuallyused
+heavily to debug the XML Catalog implementation itself.
      How to create and maintaincatalogs:
      Basically XML Catalogs are XML files, you can either use XML toolstomanage
+them or use  xmlcatalogfor this. The basic stepisto create a
+catalog the -create option provide this facility:
      orchis:~/XML -> ./xmlcatalog --create tst.xml
 <?xml version="1.0"?>
 <!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
          "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
 <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/>
-orchis:~/XML -> 
      By default xmlcatalog does not overwrite the original catalog and save the
-result on the standard output, this can be overridden using the -noout
-option. The -add command allows to add entries in the
-catalog:
      orchis:~/XML -> ./xmlcatalog --noout --create --add "public" \
+orchis:~/XML -> 
      By default xmlcatalog does not overwrite the original catalog and
+savetheresult on the standard output, this can be overridden using
+the-nooutoption. The -addcommand allows to add entries
+inthecatalog:
      orchis:~/XML -> ./xmlcatalog --noout --create --add "public" \
   "-//OASIS//DTD DocBook XML V4.1.2//EN" \
   http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd tst.xml
 orchis:~/XML -> cat tst.xml
@@ -174,83 +175,80 @@ orchis:~/XML -> cat tst.xml
 <public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
         uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/>
 </catalog>
-orchis:~/XML -> 
      The -add option will always take 3 parameters even if some of
-the XML Catalog constructs (like nextCatalog) will have only a single
-argument, just pass a third empty string, it will be ignored.
      Similarly the -del option remove matching entries from the
-catalog:
      orchis:~/XML -> ./xmlcatalog --del \
+orchis:~/XML -> 
      The -addoption will always take 3 parameters even if
+someofthe XML Catalog constructs (like nextCatalog) will have only
+asingleargument, just pass a third empty string, it will be ignored.
      Similarly the -deloption remove matching entries
+fromthecatalog:
      orchis:~/XML -> ./xmlcatalog --del \
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" tst.xml
 <?xml version="1.0"?>
 <!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
     "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
 <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/>
-orchis:~/XML -> 
      The catalog is now empty. Note that the matching of -del is
-exact and would have worked in a similar fashion with the Public ID
-string.
      This is rudimentary but should be sufficient to manage a not too complex
-catalog tree of resources.
      The implementor corner quick review of the
-API:
      First, and like for every other module of libxml, there is an
-automatically generated API page for
-catalog support.
      The header for the catalog interfaces should be included as:
      #include <libxml/catalog.h>
      The API is voluntarily kept very simple. First it is not obvious that
-applications really need access to it since it is the default behaviour of
-libxml2 (Note: it is possible to completely override libxml2 default catalog
-by using xmlSetExternalEntityLoader to
-plug an application specific resolver).
      Basically libxml2 support 2 catalog lists:
      • the default one, global shared by all the application
        • 
-  
      • a per-document catalog, this one is built if the document uses the
-    oasis-xml-catalog PIs to specify its own catalog list, it is
-    associated to the parser context and destroyed when the parsing context
-    is destroyed.
        • 
-
      the document one will be used first if it exists.
      Initialization routines:
      xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() should be
-used at startup to initialize the catalog, if the catalog should be
-initialized with specific values xmlLoadCatalog()  or xmlLoadCatalogs()
-should be called before xmlInitializeCatalog() which would otherwise do a
-default initialization first.
      The xmlCatalogAddLocal() call is used by the parser to grow the document
-own catalog list if needed.
      Preferences setup:
      The XML Catalog spec requires the possibility to select default
-preferences between  public and system delegation,
-xmlCatalogSetDefaultPrefer() allows this, xmlCatalogSetDefaults() and
-xmlCatalogGetDefaults() allow to control  if XML Catalogs resolution should
-be forbidden, allowed for global catalog, for document catalog or both, the
-default is to allow both.
      And of course xmlCatalogSetDebug() allows to generate debug messages
-(through the xmlGenericError() mechanism).
      Querying routines:
      xmlCatalogResolve(), xmlCatalogResolveSystem(), xmlCatalogResolvePublic()
-and xmlCatalogResolveURI() are relatively explicit if you read the XML
-Catalog specification they correspond to section 7 algorithms, they should
-also work if you have loaded an SGML catalog with a simplified semantic.
      xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same but
-operate on the document catalog list
      Cleanup and Miscellaneous:
      xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal() is
-the per-document equivalent.
      xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically modify the
-first catalog in the global list, and xmlCatalogDump() allows to dump a
-catalog state, those routines are primarily designed for xmlcatalog, I'm not
-sure that exposing more complex interfaces (like navigation ones) would be
-really useful.
      The xmlParseCatalogFile() is a function used to load XML Catalog files,
-it's similar as xmlParseFile() except it bypass all catalog lookups, it's
-provided because this functionality may be useful for client tools.
      threaded environments:
      Since the catalog tree is built progressively, some care has been taken to
-try to avoid troubles in multithreaded environments. The code is now thread
-safe assuming that the libxml2 library has been compiled with threads
-support.
      Other resources
      The XML Catalog specification is relatively recent so there isn't much
-literature to point at:
      • You can find a good rant from Norm Walsh about the
-    need for catalogs, it provides a lot of context informations even if
-    I don't agree with everything presented. Norm also wrote a more recent
-    article XML
-    entities and URI resolvers describing them.
        • 
-  
      • An old XML
-    catalog proposal from John Cowan
        • 
-  
      • The Resource Directory Description
-    Language (RDDL) another catalog system but more oriented toward
-    providing metadata for XML namespaces.
        • 
-  
      • the page from the OASIS Technical Committee on Entity
-    Resolution who maintains XML Catalog, you will find pointers to the
-    specification update, some background and pointers to others tools
-    providing XML Catalog support
        • 
-  
      • There is a shell script to generate
-    XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
-    directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
-    the resources found on the system. Otherwise it will just create
-    ~/xmlcatalog and ~/dbkxmlcatalog and doing:
+orchis:~/XML ->

      The catalog is now empty. Note that the matching +of-delisexact and would have worked in a similar fashion with +thePublic IDstring.

      This is rudimentary but should be sufficient to manage a not +toocomplexcatalog tree of resources.

      The implementor corner quick review +oftheAPI:

      First, and like for every other module of libxml, there is +anautomaticallygenerated API page +forcatalogsupport.

      The header for the catalog interfaces should be included as:

      #include <libxml/catalog.h>

      The API is voluntarily kept very simple. First it is not +obviousthatapplications really need access to it since it is the default +behaviouroflibxml2 (Note: it is possible to completely override libxml2 +defaultcatalogby using xmlSetExternalEntityLoadertoplug +anapplication specific resolver).

      Basically libxml2 support 2 catalog lists:

      • the default one, global shared by all the application
        • +
      • a per-document catalog, this one is built if the document + usestheoasis-xml-catalogPIs to specify its own catalog list, + itisassociated to the parser context and destroyed when the + parsingcontextis destroyed.
        • +

      the document one will be used first if it exists.

      Initialization routines:

      xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() +shouldbeused at startup to initialize the catalog, if the catalog +shouldbeinitialized with specific values xmlLoadCatalog() +orxmlLoadCatalogs()should be called before xmlInitializeCatalog() which +wouldotherwise do adefault initialization first.

      The xmlCatalogAddLocal() call is used by the parser to grow thedocumentown +catalog list if needed.

      Preferences setup:

      The XML Catalog spec requires the possibility to select +defaultpreferencesbetween public and system +delegation,xmlCatalogSetDefaultPrefer() allowsthis, xmlCatalogSetDefaults() +andxmlCatalogGetDefaults() allow to control ifXML Catalogs resolution +shouldbe forbidden, allowed for global catalog, fordocument catalog or both, +thedefault is to allow both.

      And of course xmlCatalogSetDebug() allows to generate +debugmessages(through the xmlGenericError() mechanism).

      Querying routines:

      xmlCatalogResolve(), +xmlCatalogResolveSystem(),xmlCatalogResolvePublic()and xmlCatalogResolveURI() +are relatively explicitif you read the XMLCatalog specification they +correspond to section 7algorithms, they shouldalso work if you have loaded an +SGML catalog with asimplified semantic.

      xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the +samebutoperate on the document catalog list

      Cleanup and Miscellaneous:

      xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal()isthe +per-document equivalent.

      xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically +modifythefirst catalog in the global list, and xmlCatalogDump() allows to +dumpacatalog state, those routines are primarily designed for xmlcatalog, +I'mnotsure that exposing more complex interfaces (like navigation ones) +wouldbereally useful.

      The xmlParseCatalogFile() is a function used to load XML Catalogfiles,it's +similar as xmlParseFile() except it bypass all catalog lookups,it'sprovided +because this functionality may be useful for client tools.

      threaded environments:

      Since the catalog tree is built progressively, some care has been +takentotry to avoid troubles in multithreaded environments. The code is +nowthreadsafe assuming that the libxml2 library has been compiled +withthreadssupport.

      Other resources

      The XML Catalog specification is relatively recent so there +isn'tmuchliterature to point at:

      • You can find a good rant from Norm Walsh about theneedfor + catalogs, it provides a lot of context informations even ifIdon't + agree with everything presented. Norm also wrote a morerecentarticle XMLentitiesand + URI resolversdescribing them.
        • +
      • An oldXMLcatalog + proposalfrom John Cowan
        • +
      • The Resource + DirectoryDescriptionLanguage(RDDL) another catalog system but more + orientedtowardproviding metadata for XML namespaces.
        • +
      • the page from the OASIS Technical Committee + onEntityResolutionwho maintains XML Catalog, you will find pointers + tothespecification update, some background and pointers to + otherstoolsproviding XML Catalog support
        • +
      • There is a shell scriptto + generateXMLCatalogs for DocBook 4.1.2 . If it can write to the + /etc/xml/directory,it will set-up /etc/xml/catalog and /etc/xml/docbook + based ontheresources found on the system. Otherwise it will just + create~/xmlcatalogand ~/dbkxmlcatalog and doing:

        export XML_CATALOG_FILES=$HOME/xmlcatalog

        -

        should allow to process DocBook documentations without requiring - network accesses for the DTD or stylesheets

        +

        should allow to process DocBook documentations withoutrequiringnetwork + accesses for the DTD or stylesheets

        • -
      • I have uploaded a - small tarball containing XML Catalogs for DocBook 4.1.2 which seems - to work fine for me too
        • -
      • The xmlcatalog - manual page
        • -

      If you have suggestions for corrections or additions, simply contact -me:

      Daniel Veillard

    +
  • I have uploaded asmalltarballcontaining + XML Catalogs for DocBook 4.1.2 which seemsto workfine for me too
    • +
  • The xmlcatalogmanualpage
    • +

    If you have suggestions for corrections or additions, simply contactme:

    Daniel Veillard

    diff --git a/doc/contribs.html b/doc/contribs.html index e493eb3..2163d60 100644 --- a/doc/contribs.html +++ b/doc/contribs.html @@ -7,34 +7,29 @@ H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } -Contributions
    Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
    Made with Libxml2 Logo

    The XML C parser and toolkit of Gnome

    Contributions

    Main Menu
    Related links