bpo-33187: Document ElementInclude (XInclude) support in ElementTree (GH-8861)
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 1b4e2c9..abc15d4 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -738,6 +738,95 @@
:class:`Element` instance and a dictionary.
+.. _elementtree-xinclude:
+
+XInclude support
+----------------
+
+This module provides limited support for
+`XInclude directives <https://www.w3.org/TR/xinclude/>`_, via the :mod:`xml.etree.ElementInclude` helper module. This module can be used to insert subtrees and text strings into element trees, based on information in the tree.
+
+Example
+^^^^^^^
+
+Here's an example that demonstrates use of the XInclude module. To include an XML document in the current document, use the ``{http://www.w3.org/2001/XInclude}include`` element and set the **parse** attribute to ``"xml"``, and use the **href** attribute to specify the document to include.
+
+.. code-block:: xml
+
+ <?xml version="1.0"?>
+ <document xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="source.xml" parse="xml" />
+ </document>
+
+By default, the **href** attribute is treated as a file name. You can use custom loaders to override this behaviour. Also note that the standard helper does not support XPointer syntax.
+
+To process this file, load it as usual, and pass the root element to the :mod:`xml.etree.ElementTree` module:
+
+.. code-block:: python
+
+ from xml.etree import ElementTree, ElementInclude
+
+ tree = ElementTree.parse("document.xml")
+ root = tree.getroot()
+
+ ElementInclude.include(root)
+
+The ElementInclude module replaces the ``{http://www.w3.org/2001/XInclude}include`` element with the root element from the **source.xml** document. The result might look something like this:
+
+.. code-block:: xml
+
+ <document xmlns:xi="http://www.w3.org/2001/XInclude">
+ <para>This is a paragraph.</para>
+ </document>
+
+If the **parse** attribute is omitted, it defaults to "xml". The href attribute is required.
+
+To include a text document, use the ``{http://www.w3.org/2001/XInclude}include`` element, and set the **parse** attribute to "text":
+
+.. code-block:: xml
+
+ <?xml version="1.0"?>
+ <document xmlns:xi="http://www.w3.org/2001/XInclude">
+ Copyright (c) <xi:include href="year.txt" parse="text" />.
+ </document>
+
+The result might look something like:
+
+.. code-block:: xml
+
+ <document xmlns:xi="http://www.w3.org/2001/XInclude">
+ Copyright (c) 2003.
+ </document>
+
+Reference
+---------
+
+.. _elementinclude-functions:
+
+Functions
+^^^^^^^^^
+
+.. function:: xml.etree.ElementInclude.default_loader( href, parse, encoding=None)
+
+ Default loader. This default loader reads an included resource from disk. *href* is a URL.
+ *parse* is for parse mode either "xml" or "text". *encoding*
+ is an optional text encoding. If not given, encoding is ``utf-8``. Returns the
+ expanded resource. If the parse mode is ``"xml"``, this is an ElementTree
+ instance. If the parse mode is "text", this is a Unicode string. If the
+ loader fails, it can return None or raise an exception.
+
+
+.. function:: xml.etree.ElementInclude.include( elem, loader=None)
+
+ This function expands XInclude directives. *elem* is the root element. *loader* is
+ an optional resource loader. If omitted, it defaults to :func:`default_loader`.
+ If given, it should be a callable that implements the same interface as
+ :func:`default_loader`. Returns the expanded resource. If the parse mode is
+ ``"xml"``, this is an ElementTree instance. If the parse mode is "text",
+ this is a Unicode string. If the loader fails, it can return None or
+ raise an exception.
+
+
.. _elementtree-element-objects:
Element Objects