Using a single chapter for the API docs and a single chapter for the ZCML directives made it hard to read.

1 files changed, 73 insertions, 0 deletions

diff --git a/docs/zcml/include.rst b/docs/zcml/include.rst
new file mode 100644
index 000000000..5e22f584a
--- /dev/null
+++ b/docs/zcml/include.rst
@@ -0,0 +1,73 @@
+.. _include_directive:
+
+``include``
+-----------
+
+The ``include`` directive includes configuration from an external ZCML
+file.  Use of the ``include`` tag allows a user to split configuration
+across multiple ZCML files, and allows package distributors to provide
+default ZCML configuration for specific purposes which can be
+included by the integrator of the package as necessary.
+
+Attributes
+~~~~~~~~~~
+
+``package``
+
+   A :term:`dotted Python name` which references a Python :term:`package`.
+
+``filename``
+
+   An absolute or relative filename which references a ZCML file.
+
+The ``package`` and ``filename`` attributes can be used together or
+separately as necessary.
+
+Examples
+~~~~~~~~
+
+.. topic:: Loading the File Named ``configure.zcml`` from a Package Implicitly
+
+   .. code-block:: xml
+      :linenos:
+
+      <include package="some.package" />
+
+.. topic:: Loading the File Named ``other.zcml`` From the Current Package
+
+   .. code-block:: xml
+      :linenos:
+
+      <include filename="other.zcml" />
+
+.. topic:: Loading a File From a Subdirectory of the Current Package
+
+   .. code-block:: xml
+      :linenos:
+
+      <include filename="subdir/other.zcml" />
+
+.. topic:: Loading the File Named ``/absolute/path/other.zcml``
+
+   .. code-block:: xml
+      :linenos:
+
+      <include filename="/absolute/path/other.zcml" />
+
+.. topic:: Loading the File Named ``other.zcml`` From a Package Explicitly
+
+   .. code-block:: xml
+      :linenos:
+
+      <include package="some.package" filename="other.zcml" />
+
+Alternatives
+~~~~~~~~~~~~
+
+None.
+
+See Also
+~~~~~~~~
+
+See also :ref:`helloworld_declarative`.
+