Do not use the --docbook option of xsltproc to process XML DocBook documents, this option is only intended to provide some (limited) support of diff --git a/doc/python.html b/doc/python.html index 67ad685b..37b108f6 100644 --- a/doc/python.html +++ b/doc/python.html @@ -84,7 +84,7 @@ or libxslt wrappers or bindings:
Matt Sergeant developped XML::LibXML and - XML::LibXSLT, a perl wrapper for libxml2/libxslt as part of the AxKit XML application server + XML::LibXSLT, a perl wrapper for libxml2/libxslt as part of the AxKit XML application serverThe libxslt Python module depends on the libxml2 Python module. -
+The libxslt Python module depends on the libxml2 Python module.
The distribution includes a set of Python bindings, which are garanteed to
be maintained as part of the library in the future, though the Python
interface have not yet reached the maturity of the C API. The distribution
@@ -109,8 +107,8 @@ includes a set of examples and regression tests for the python bindings in
the python/tests directory. Here are some excepts from those
tests:
This is a basic test of XSLT interfaces: loading a stylesheet and -a document, transforming the document and saving the result.
+This is a basic test of XSLT interfaces: loading a stylesheet and a +document, transforming the document and saving the result.
import libxml2 import libxslt @@ -127,28 +125,32 @@ for the operations on XML trees. Let's have a look at the objects manipulated in that example and how is the processing done:
styledoc: is a libxml2 document tree. It is obtained by
- parsing the XML file "test.xsl" containing the stylesheet.styledoc
+ : is a libxml2 document tree. It is obtained by parsing the XML file
+ "test.xsl" containing the stylesheet.style: this is a precompiled stylesheet ready to be used
- by the following transformations (note the plural form, multiple
- transformations can resuse the same stylesheet).style
+ : this is a precompiled stylesheet ready to be used by the following
+ transformations (note the plural form, multiple transformations can
+ resuse the same stylesheet).
doc: this is the document to apply the transformation to.
- In this case it is simply generated by parsing it from a file but any
- other processing is possible as long as one get a libxml2 Doc. Note
- that HTML tree are suitable for XSLT processing in libxslt. This is
- actually how this page is generated !doc
+ : this is the document to apply the transformation to. In this case it is
+ simply generated by parsing it from a file but any other processing is
+ possible as long as one get a libxml2 Doc. Note that HTML tree are
+ suitable for XSLT processing in libxslt. This is actually how this page
+ is generated !
result: this is a document generated by applying the
- stylesheet to the document. Note that some of the stylesheet informations
- may be related to the serialization of that document and as in this
- example a specific saveResultToFilename() method of the stylesheet
- should be used to save it to a file (in that case to "foo").result
+ : this is a document generated by applying the stylesheet to the
+ document. Note that some of the stylesheet informations may be related to
+ the serialization of that document and as in this example a specific
+ saveResultToFilename() method of the stylesheet should be used to save it
+ to a file (in that case to "foo").
Also note the need to explicitely deallocate documents with freeDoc() -except for the stylesheet document which is freed when its compiled form -is garbage collected.
+except for the stylesheet document which is freed when its compiled form is +garbage collected.This one is a far more complex test. It shows how to modify the behaviour of an XSLT transformation by passing parameters and how to extend the XSLT @@ -175,25 +177,22 @@ def f(ctx, str): return string.upper(str) libxslt.registerExtModuleFunction("foo", "http://example.com/foo", f) -
This code defines and register an extension function. Note that the +
This code defines and register an extension function. Note that the function can be bound to any name (foo) and how the binding is also -associated to a namespace name "http://example.com/foo". From an -XSLT point of view the function just returns an upper case version of the -string passed as a parameter. But the first part of the function also -read some contextual information from the current XSLT processing environement, -in that case it looks for the current insertion node in the resulting output -(either the resulting document or the Result Value Tree being generated), and -saves it to a global variable for checking that the access actually worked. -
-For more informations on the xpathParserContext and transformContext +associated to a namespace name "http://example.com/foo". From an XSLT point +of view the function just returns an upper case version of the string passed +as a parameter. But the first part of the function also read some contextual +information from the current XSLT processing environement, in that case it +looks for the current insertion node in the resulting output (either the +resulting document or the Result Value Tree being generated), and saves it to +a global variable for checking that the access actually worked.
+For more informations on the xpathParserContext and transformContext objects check the libray internals description. The pctxt is actually an object from a class derived from the -libxml2.xpathParserContext() with just a couple more properties including -the possibility to look up the XSLT transformation context from the XPath -context. -
-
-styledoc = libxml2.parseDoc("""
+libxml2.xpathParserContext() with just a couple more properties including the
+possibility to look up the XSLT transformation context from the XPath
+context.
+styledoc = libxml2.parseDoc("""
<xsl:stylesheet version='1.0'
xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
xmlns:foo='http://example.com/foo'
@@ -205,34 +204,27 @@ styledoc = libxml2.parseDoc("""
</xsl:template>
</xsl:stylesheet>
""")
- Here is a simple example of how to read an XML document from a python
-string with libxml2. Note how this stylesheet:
-
+Here is a simple example of how to read an XML document from a python
+string with libxml2. Note how this stylesheet:
bar
-bar
style = libxslt.parseStylesheetDoc(styledoc)
doc = libxml2.parseDoc("<doc/>")
result = style.applyStylesheet(doc, { "bar": "'success'" })
style.freeStylesheet()
doc.freeDoc()
-that part is identical, to the basic example except that the -transformation is passed a dictionnary of parameters. Note that the -string passed "success" had to be quoted, otherwise it is interpreted -as an XPath query for the childs of root named "success". -
--root = result.children ++that part is identical, to the basic example except that the +transformation is passed a dictionnary of parameters. Note that the string +passed "success" had to be quoted, otherwise it is interpreted as an XPath +query for the childs of root named "success".
+root = result.children if root.name != "article": print "Unexpected root node name" sys.exit(1) @@ -243,27 +235,20 @@ if nodeName != 'article': print "The function callback failed to access its context" sys.exit(1) -result.freeDoc() --That part just verifies that the transformation worked, that the parameter +result.freeDoc()
That part just verifies that the transformation worked, that the parameter got properly passed to the engine, that the function f() got called and that -it properly accessed the context to find the name of the insertion node. - -
+it properly accessed the context to find the name of the insertion node.this module is a bit too long to be described there but it is basically -a rewrite of the xsltproc command line interface of libxslt in Python. It +
this module is a bit too long to be described there but it is basically a +rewrite of the xsltproc command line interface of libxslt in Python. It provides nearly all the functionalities of xsltproc and can be used as a base -module to write Python customized XSLT processors. One of the thing -to notice are: -
+module to write Python customized XSLT processors. One of the thing to notice +are:libxml2.lineNumbersDefault(1) -libxml2.substituteEntitiesDefault(1) --
those two calls in the main() function are needed to force the libxml2 -processor to generate DOM trees compliant with the XPath data model. - -
+libxml2.substituteEntitiesDefault(1) +those two calls in the main() function are needed to force the libxml2 +processor to generate DOM trees compliant with the XPath data model.
diff --git a/doc/xslt.html b/doc/xslt.html index d6b8843e..b8fc611e 100644 --- a/doc/xslt.html +++ b/doc/xslt.html @@ -602,6 +602,9 @@ few pointers and informations which may be helpful:Do not use the --docbook option of xsltproc to process XML DocBook @@ -664,7 +667,7 @@ or libxslt wrappers or bindings:
href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt Sergeant developped XML::LibXML and - XML::LibXSLT, a perl wrapper for libxml2/libxslt as part of the , a perl wrapper for libxml2/libxslt as part of the AxKit XML application serverThe libxslt Python module depends on the libxml2 Python module. +
The libxslt Python module depends on the libxml2 Python module.
+The distribution includes a set of Python bindings, which are garanteed to be maintained as part of the library in the future, though the Python interface have not yet reached the maturity of the C API. The distribution @@ -692,8 +697,8 @@ tests:
This is a basic test of XSLT interfaces: loading a stylesheet and -a document, transforming the document and saving the result.
+This is a basic test of XSLT interfaces: loading a stylesheet and a +document, transforming the document and saving the result.
import libxml2 import libxslt @@ -710,28 +715,33 @@ result.freeDoc()for the operations on XML trees. Let's have a look at the objects manipulated in that example and how is the processing done:
styledoc: is a libxml2 document tree. It is obtained by
- parsing the XML file "test.xsl" containing the stylesheet.style: this is a precompiled stylesheet ready to be used
- by the following transformations (note the plural form, multiple
- transformations can resuse the same stylesheet).doc: this is the document to apply the transformation to.
- In this case it is simply generated by parsing it from a file but any
- other processing is possible as long as one get a libxml2 Doc. Note
- that HTML tree are suitable for XSLT processing in libxslt. This is
- actually how this page is generated !result: this is a document generated by applying the
- stylesheet to the document. Note that some of the stylesheet informations
- may be related to the serialization of that document and as in this
- example a specific saveResultToFilename() method of the stylesheet
- should be used to save it to a file (in that case to "foo").styledoc
+ : is a libxml2 document tree. It is obtained by parsing the XML file
+ "test.xsl" containing the stylesheet.style
+ : this is a precompiled stylesheet ready to be used by the following
+ transformations (note the plural form, multiple transformations can
+ resuse the same stylesheet).doc
+ : this is the document to apply the transformation to. In this case it is
+ simply generated by parsing it from a file but any other processing is
+ possible as long as one get a libxml2 Doc. Note that HTML tree are
+ suitable for XSLT processing in libxslt. This is actually how this page
+ is generated !result
+ : this is a document generated by applying the stylesheet to the
+ document. Note that some of the stylesheet informations may be related to
+ the serialization of that document and as in this example a specific
+ saveResultToFilename() method of the stylesheet should be used to save it
+ to a file (in that case to "foo").Also note the need to explicitely deallocate documents with freeDoc() -except for the stylesheet document which is freed when its compiled form -is garbage collected.
+except for the stylesheet document which is freed when its compiled form is +garbage collected.This one is a far more complex test. It shows how to modify the behaviour of an XSLT transformation by passing parameters and how to extend the XSLT engine with functions defined in python:
@@ -757,23 +767,24 @@ def f(ctx, str): return string.upper(str) libxslt.registerExtModuleFunction("foo", "http://example.com/foo", f) -This code defines and register an extension function. Note that the + +
This code defines and register an extension function. Note that the function can be bound to any name (foo) and how the binding is also -associated to a namespace name "http://example.com/foo". From an -XSLT point of view the function just returns an upper case version of the -string passed as a parameter. But the first part of the function also -read some contextual information from the current XSLT processing environement, -in that case it looks for the current insertion node in the resulting output -(either the resulting document or the Result Value Tree being generated), and -saves it to a global variable for checking that the access actually worked. -
For more informations on the xpathParserContext and transformContext +associated to a namespace name "http://example.com/foo". From an XSLT point +of view the function just returns an upper case version of the string passed +as a parameter. But the first part of the function also read some contextual +information from the current XSLT processing environement, in that case it +looks for the current insertion node in the resulting output (either the +resulting document or the Result Value Tree being generated), and saves it to +a global variable for checking that the access actually worked.
+ +For more informations on the xpathParserContext and transformContext objects check the libray internals description. The pctxt is actually an object from a class derived from the -libxml2.xpathParserContext() with just a couple more properties including -the possibility to look up the XSLT transformation context from the XPath -context. -
-styledoc = libxml2.parseDoc("""
+libxml2.xpathParserContext() with just a couple more properties including the
+possibility to look up the XSLT transformation context from the XPath
+context.
+styledoc = libxml2.parseDoc("""
<xsl:stylesheet version='1.0'
xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
xmlns:foo='http://example.com/foo'
@@ -785,28 +796,28 @@ styledoc = libxml2.parseDoc("""
</xsl:template>
</xsl:stylesheet>
""")
- Here is a simple example of how to read an XML document from a python
-string with libxml2. Note how this stylesheet:
-
bar
-Here is a simple example of how to read an XML document from a python +string with libxml2. Note how this stylesheet:
+barstyle = libxslt.parseStylesheetDoc(styledoc)
doc = libxml2.parseDoc("<doc/>")
result = style.applyStylesheet(doc, { "bar": "'success'" })
style.freeStylesheet()
doc.freeDoc()
-that part is identical, to the basic example except that the -transformation is passed a dictionnary of parameters. Note that the -string passed "success" had to be quoted, otherwise it is interpreted -as an XPath query for the childs of root named "success". -
-root = result.children + ++ +that part is identical, to the basic example except that the +transformation is passed a dictionnary of parameters. Note that the string +passed "success" had to be quoted, otherwise it is interpreted as an XPath +query for the childs of root named "success".
+root = result.children if root.name != "article": print "Unexpected root node name" sys.exit(1) @@ -817,23 +828,24 @@ if nodeName != 'article': print "The function callback failed to access its context" sys.exit(1) -result.freeDoc() --That part just verifies that the transformation worked, that the parameter +result.freeDoc()
That part just verifies that the transformation worked, that the parameter got properly passed to the engine, that the function f() got called and that -it properly accessed the context to find the name of the insertion node. +it properly accessed the context to find the name of the insertion node.
this module is a bit too long to be described there but it is basically -a rewrite of the xsltproc command line interface of libxslt in Python. It + +
this module is a bit too long to be described there but it is basically a +rewrite of the xsltproc command line interface of libxslt in Python. It provides nearly all the functionalities of xsltproc and can be used as a base -module to write Python customized XSLT processors. One of the thing -to notice are: +module to write Python customized XSLT processors. One of the thing to notice +are:
libxml2.lineNumbersDefault(1) -libxml2.substituteEntitiesDefault(1) --
those two calls in the main() function are needed to force the libxml2 -processor to generate DOM trees compliant with the XPath data model. +libxml2.substituteEntitiesDefault(1) + +
those two calls in the main() function are needed to force the libxml2 +processor to generate DOM trees compliant with the XPath data model.
I'm still waiting for someone to contribute a simple XSLT processing