[Lxml-checkins] r44179 - lxml/branch/lxml-1.3/doc

[scoder at codespeak.net]

Author: scoder
Date: Tue Jun 12 18:38:31 2007
New Revision: 44179

Modified:
   lxml/branch/lxml-1.3/doc/api.txt
Log:
merged in XInclude doc update from trunk

Modified: lxml/branch/lxml-1.3/doc/api.txt
==============================================================================
--- lxml/branch/lxml-1.3/doc/api.txt	(original)
+++ lxml/branch/lxml-1.3/doc/api.txt	Tue Jun 12 18:38:31 2007
@@ -32,7 +32,7 @@
    4  Iteration
    5  Error handling on exceptions
    6  Serialisation
-   7  xinclude
+   7  XInclude and ElementInclude
    8  write_c14n on ElementTree
 
 
@@ -257,11 +257,11 @@
 .. _`Unicode support`: parsing.html#python-unicode-strings
 
 
-XInclude
---------
+XInclude and ElementInclude
+---------------------------
 
-Simple XInclude support exists.  You can let lxml process xinclude statements
-in a document by calling the xinclude() method on a tree::
+You can let lxml process xinclude statements in a document by calling the
+xinclude() method on a tree::
 
   >>> data = StringIO('''\
   ... <doc xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -271,8 +271,19 @@
 
   >>> tree = etree.parse(data)
   >>> tree.xinclude()
-  >>> etree.tostring(tree.getroot())
-  '<doc xmlns:xi="http://www.w3.org/2001/XInclude">\n<foo/>\n<a xml:base="doc/test.xml"/>\n</doc>'
+  >>> print etree.tostring(tree.getroot())
+  <doc xmlns:xi="http://www.w3.org/2001/XInclude">
+  <foo/>
+  <a xml:base="doc/test.xml"/>
+  </doc>
+
+Note that the ElementTree compatible ElementInclude_ module is also supported
+as ``lxml.ElementInclude``.  It has the additional advantage of supporting
+custom `URL resolvers`_ at the Python level.  The normal XInclude mechanism
+cannot deploy these.  If you need ElementTree compatibility or custom
+resolvers, you have to stick to the external Python module.
+
+.. _ElementInclude: http://effbot.org/zone/element-xinclude.htm
 
 
 write_c14n on ElementTree