From 831da8a6969703d79c4efb27a96c734140babf45 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 26 Dec 2009 19:23:29 +0000 Subject: - Created new top-level documentation section: "ZCML Directives". This section contains detailed ZCML directive information, some of which was removed from various narrative chapters. --- docs/narr/configuration.rst | 67 +++++++-------------------------------------- 1 file changed, 10 insertions(+), 57 deletions(-) (limited to 'docs/narr/configuration.rst') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 3183d278a..049be2ca3 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -521,6 +521,8 @@ a good deal of what's going on "under the hood" when we configure a :mod:`repoze.bfg` application imperatively. However, another mode of configuration exists named *declarative* configuration. +.. _helloworld_declarative: + Hello World, Configured Declaratively ------------------------------------- @@ -663,19 +665,16 @@ The ``configure.zcml`` ZCML file contains this bit of XML: :linenos: - ... body ... + Because :term:`ZCML` is XML, and because XML requires a single root tag for each document, every ZCML file used by :mod:`repoze.bfg` must -contain a ```` container tag, which acts as the root XML -tag. Usually, the start tag of the ```` container tag has -a default namespace associated with it. In the file above, the -``xmlns="http://namepaces.repoze.org/bfg"`` attribute of the -``configure`` start tag names the default XML namespace, which is -``http://namespaces.repoze.org/bfg``. See -:ref:`word_on_xml_namespaces` for more information about XML -namespaces. +contain a ``configure`` container directive, which acts as the root +XML tag. It is a "container" directive because its only job is to +contain other directives. + +See also :ref:`configure_directive` and :ref:`word_on_xml_namespaces`. The ```` Tag ~~~~~~~~~~~~~~~~~~~~~ @@ -719,6 +718,8 @@ However, the ```` tag needs to exist only in a "top-level" ZCML file, it needn't also exist in ZCML files *included by* a top-level ZCML file. +See also :ref:`include_directive`. + The ```` Tag ~~~~~~~~~~~~~~~~~~ @@ -839,54 +840,6 @@ application, a :data:`repoze.bfg.exceptions.ConfigurationError` will be raised when you attempt to start the application with information about which tags might have conflicted. -.. _word_on_xml_namespaces: - -A Word On XML Namespaces -~~~~~~~~~~~~~~~~~~~~~~~~ - -Using the ``http://namespaces.repoze.org/bfg`` namespace as the -default XML namespace isn't strictly necessary; you can use a -different default namespace as the default. However, if you do, the -declaration tags which are defined by :mod:`repoze.bfg` such as the -```` declaration tag will need to be defined in such a way that -the XML parser that :mod:`repoze.bfg` uses knows which namespace the -:mod:`repoze.bfg` tags are associated with. For example, the -following files are all completely equivalent: - -.. topic:: Use of A Non-Default XML Namespace - - .. code-block:: xml - :linenos: - - - - - - - - - -.. topic:: Use of A Per-Tag XML Namespace Without A Default XML Namespace - - .. code-block:: xml - :linenos: - - - - - - - - - -For more information about XML namespaces, see `this older, but simple -XML.com article `_. - Conclusions ----------- -- cgit v1.2.3