One namespace for ZCML
======================

:Author:   Philipp von Weitershausen, philikon@philikon.de
:Status:   IsProposal
:Date:     $Date$
:Original: $URL$

Current status
--------------

In ZCML, a directive can be associated with a certain XML namespace.
Usually, directives of the same concern are associated with the same
namespace.  Only three very general directives are available in all
namespaces (``configure``, ``include``, ``includeOverrides``).  In
Zope 3.2/2.9, we have the following namespaces (all using
http://namespaces.zope.org/ as a URI prefix):

* apidoc (3 directives)

* browser (26 directives)

* dav (1 directive)

* help (1 directive)

* i18n (1 directive)

* mail (3 directives)

* meta (7 directives)

* rdb (2 directives)

* renderer (1 directive)

* tales (1 directive)

* xmlrpc (1 directive)

* zope (32 directives)

* zcml (1 attribute: ``zcml:condition``)

* five (11 directives)

In a typical Zope 3 application, an estimated 90% of the directives
are either from the ``zope`` or the ``browser`` namespace, in a Five
application this also includes the ``five`` namespace.

Problems
--------

* There are a large number of people who see XML namespaces,
  especially their explicit definition, as dead chickens and a burden
  for the developer.

* Some namespaces only contain 1 directive, so for the sake of using
  this one directive, you have to declare an extra namespace.

* The distinction which goes into what namespace is highly
  inconsistent.

* The usage of different namespace in ZCML might have encouraged third
  party packages to come up with their own ZCML directives.  This has
  become a problem, as ReducingTheAmountOfZCMLDirectives_ points out.

* It is arguable whether ZCML misuses namespaces.  XML namespaces were
  invented and are used so that one can mix different XML dialects
  (e.g. XHTML, SVG and XForms) in one document.  ZCML, however, uses
  namespaces to separate directives of different concerns, not
  different forms of XML markup.  Plus, every XML element it
  encounters is treated as a directive call by ZCML, making it
  impossible to mix other XML into ZCML (e.g. DocBook for inline
  documentation).


Proposal
--------

The author has suggested_ before that one namespace for all ZCML
directives would suffice.  This has generally received positive
feedback.

.. _suggested: http://mail.zope.org/pipermail/zope3-dev/2006-January/017625.html

Details
~~~~~~~

In the future, there will only be two possible ZCML namespaces: The
``zope`` namespace for basically all directives except meta-directives
and ``zcml`` for meta-directives.  Directives registered with ZCML are
implicitly available on the ``zope`` namespace and only on that
namespace.  ZCML will ignore elements on other namespaces than
``zope`` and ``zcml``.

For Zope 3.3/2.10, we will rename all existing directives to be part
of the ``zope`` namespace, providing their old namespace'd aliases for
BBB during 12 months.  Using these aliases will render deprecation
warnings.  In Zope 3.5/2.12 we will drop those aliases.  Same applies
to the ``meta`` directives and the ``zcml`` namespace.

More details
~~~~~~~~~~~~

* ``zcml:condition`` will continue to work as it does now.

* ``meta`` directives retain their names in the ``zcml`` namespace.
  Only ``meta:directives`` (notice the plural) will go away without
  replacement, it is just a tool that saves typing when putting
  directives on a particular namespace.

* ``configure``, ``include``, ``includeOverrides`` will become part of
  the ``zope`` namespace.  Their "feature" of being available all the
  time will disappear.

* ``browser`` directives will be prefixed with ``browser`` and assume
  CamelCase (e.g. ``browserPage``, ``browserSkin``), etc.  Same rule
  will be applied to ``apidoc``, ``xmlrpc``, ``mail`` and ``tales``
  directives.

* ``dav``, ``renderer`` and ``rdb`` directives will go away (per
  ReducingTheAmountOfZCMLDirectives_).

* ``help:register`` will become ``registerHelp``.

* ``i18n:registerTranslation`` will become ``registerLocales``

.. _ReducingTheAmountOfZCMLDirectives: http://dev.zope.org/Zope3/ReducingTheAmountOfZCMLDirectives


Risks
-----

* This is a BIG and drastic change.  It might be intimidating for
  people just getting familiar or having gotten familiar with Zope 3
  and ZCML.  It will also have large effects on advanced third party
  packages.  However, ZCML has received a lot of criticism lately.
  Even though radical, the idea of this proposal was received
  positively on the mailinglists as a means to improve ZCML.  Together
  with ReducingTheAmountOfZCMLDirectives_, the author considers it an
  important step into a better ZCML experience.

* This proposal will invalidate a lot of documentation, especially
  printed books.  The author of this proposal (who is also the author
  of a Zope 3 book) believes, however, that the benefits of a simpler
  ZCML set-up outweigh the burden on Zope 3 documenters.  In the long
  run, a simpler ZCML should also lift the burden on Zope 3
  documenters.

* ZCML namespaces perhaps made it a bit easier to navigate around the
  flood of ZCML directives (this is speculative).  This "feature"
  would go away.  However, there's an on-going discussion that aims at
  reducing the amount of ZCML directives, so this problem might be
  getting smaller in the future.


Implementation status
---------------------

None so far, still in discussion