doc: added wildcard xinclude docs that were lost in merge

1 files changed, 38 insertions, 0 deletions

diff --git a/doc/server/xml-common.txt b/doc/server/xml-common.txt
index f35c1bd23..aa414dc48 100644
--- a/doc/server/xml-common.txt
+++ b/doc/server/xml-common.txt
@@ -278,11 +278,49 @@ pieces.  For instance, in the :ref:`server-plugins-grouping-metadata`
 To enable XInclude on a file, you need only add the XInclude namespace
 to the top-level tag.
 
+You can also *optionally* include a file that may or may not exist
+with the ``fallback`` tag:
+
+.. code-block:: xml
+
+    <Groups xmlns:xi="http://www.w3.org/2001/XInclude">
+      <xi:include href="my-groups.xml"/>
+      <xi:include href="their-groups.xml"><xi:fallback/></xi:include>
+    </Groups>
+
+In this case, if ``their-groups.xml`` does not exist, no error will be
+raised and everything will work fine.  (You can also use ``fallback``
+to include a different file, or explicit content in the case that the
+parent include does not exist.)
+
 XInclude can only include complete, well-formed XML files.  In some
 cases, it may not be entirely obvious or intuitive how to structure
 such an included file to conform to the schema, although in general
 the included files should be structure exactly like the parent file.
 
+Wildcard XInclude
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.3.1
+
+Bcfg2 supports an extension to XInclude that allows you to use shell
+globbing in the hrefs.  (Stock XInclude doesn't support this, since
+the href is supposed to be a URL.)
+
+For instance:
+
+.. code-block:: xml
+
+    <Groups xmlns:xi="http://www.w3.org/2001/XInclude">
+      <xi:include href="groups/*.xml"/>
+    </Groups>
+
+This would include all ``*.xml`` files in the ``groups`` subdirectory.
+
+Note that if a glob finds no files, that is treated the same as if a
+single included file does not exist.  You should use the ``fallback``
+tag, described above, if a glob may potentially find no files.
+
 Feature Matrix
 ==============