[Zope3-dev] ZCML alternative

[Phillip J. Eby]

At 08:37 AM 6/3/02 -0400, Jim Fulton wrote:

>I'll point out that this thread isn't going anywhere. We are
>not going to stop using ZCML. Consider this a Papal edict.

But there is one interesting idea that comes to mind from it, regarding 
ease of understanding ZCML...

Suppose that ZCML namespace URLs were required (by convention) to be 
documentation for the contents of that namespace?

That is, http://namespaces.zope.org/security/ would be a page on the 
security namespace, with pages for the various directives contained 
therein.  This could be done as easily by third-party component creators as 
for Zope core components.  And in the case of core components, there could 
be a place in the Zope 3 distribution that corresponded to the 
http://namespaces.zope.org/ tree, so that the docs are locally available, 
and so that Zope developers could update the docs when they're updating the 
directives.

With an appropriate documentation format, one could even define a unit test 
that cross-checked the source ZCML files against the docs to ensure that no 
undocumented directives or attributes thereof were being used, so that 
failing to document a new directive or updated syntax would "break the 
build".  :)

Maybe that is going a little far, but I do agree with Shane that 
understanding ZCML right now is *hard*.  If we're solidifying ZCML, perhaps 
it's time to solidify a location for its documentation...  Given that the 
namespace URL's have to be in the ZCML for it to work, they seem like a 
good place.