[Lxml-checkins] r42243 - lxml/trunk/doc

[scoder at codespeak.net]

Author: scoder
Date: Sun Apr 22 20:58:16 2007
New Revision: 42243

Modified:
   lxml/trunk/doc/api.txt
Log:
note on ElementInclude support

Modified: lxml/trunk/doc/api.txt
==============================================================================
--- lxml/trunk/doc/api.txt	(original)
+++ lxml/trunk/doc/api.txt	Sun Apr 22 20:58:16 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">
@@ -274,6 +274,14 @@
   >>> etree.tostring(tree.getroot())
   '<doc xmlns:xi="http://www.w3.org/2001/XInclude">\n<foo/>\n<a xml:base="doc/test.xml"/>\n</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
 -------------------------