[Zope-dev] my take on ZCML's includeOverrides

[Chris McDonough]

Independent of my previous call for discussion about ZCML conflict
resolution, I'm cutting and pasting my side of a discussion about the
ZCML "includeOverrides" directive from an IRC chat, because it may come
in useful for folks grappling with its behavior.  There's not really any
human-consumable docs about it.

If I've made any mistakes, please let me know.

[13:42] <mcdonc> so ftr, i've found that ZCML's includeOverrides and
include to do (at least on one vector) exactly the opposite of what you
might expect them to do
[13:42] <mcdonc> "includeOverrides" is a poor name
[13:42] <mcdonc> what it does is to emulate the behavior of inlining
stuff into the file you use it from
[13:43] <mcdonc> when you use includeOverrides it's as if you typed all
the directives in the included file into the file you're including from
[13:43] <mcdonc> otoh, "include" doesnt behave like this
[13:44] <mcdonc> you can actually define the same directive in three
files
[13:44] <mcdonc> configure.zcml, one.zcml, and two.zcml
[13:44] <mcdonc> and if you use "include" from configure.zcml of one and
two
[13:44] <mcdonc> there will be no conflict
[13:45] <mcdonc> this is because non-conflicting "rootmost" directives
win
[13:45] <mcdonc> otoh, if you use includeOverrides of one and two from
configure.zcml
[13:45] <mcdonc> all three will conflict
[13:45] <mcdonc> because its as if you typed them all in configure.zcml
by hand
[13:45] <mcdonc> and that means there are three conflicting rootmost
directives
[13:46] <mcdonc> if you mentally substitute "inline" for
"includeOverrides" it makes a little more sense
[13:48] <mcdonc> override is exactly the wrong phrase to use in the name
of this directive
[13:51] <mcdonc> what it boils down to is that you never, ever really
want to use includeOverrides except in your rootmost zcml file
[13:51] <mcdonc> and probably not even there
[13:51] <mcdonc> because you can get the same effect by typing the
directives there by hand

- C