[Zope3-dev] proposal to extend meta.zcml files with documentation strings

[Shane Hathaway]

R. David Murray wrote:
> I've posted a propsal for making it easier to maintain the essential
> zcml documentation by adding documentation strings to the meta.zcml
> files.  Please comment.  I've got proof-of-concept code that I'll
> keep working on unless I hear screams of pain <grin>.
> 
> http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/ZCMLHelpViaMetaConfiguration

Here are my thoughts on the subject, FWIW.  We're making great progress 
by separating software from configuration, but the current 
implementation in Zope 3 has some issues.

The main trouble I've had with ZCML is that it's hard to find the Python 
code it supposedly invokes.  In fact, it seems to try to hide the 
association.  I realize there need to be multiple passes over the 
configuration (Jim and I came up with the multiple pass idea together, 
after all!) but the current coupling between directives and executable 
code is much too loose.  Figuring out exactly what code will be executed 
as the result of an active directive is too difficult.

My proposed solution to this is to use objects, not tuples.  A directive 
should be represented as an object.  A configuration file should be an 
object.  An active configuration should be an object.  I think it could 
lift a lot of the complexity of Zope 3 configuration.  I've been 
drafting rough interfaces, if anyone is interested.

Also, I think configuration in XML has great benefits, but coding 
"meta-configuration" in XML adds to the complexity burden without a 
benefit that I'm aware of.  We envision site developers changing the 
software configuration, but do we envision them changing the software 
configuration configuration?  Imagine you're designing a home through a 
contractor.  You'd want to specify the layout of the rooms, but you 
wouldn't want to specify the format of the blueprints.  That's up to the 
contractor.

Shane