That's a fair question.
This is a pattern I have learned by using Docbook 5.0, which is another
one of those
Norm uses the RelaxNG annotations namespace.
I like the design principle RelaxNG uses for namespaces:
"RELAX NG doesn't define specific elements and attributes reserved for
annotations. Instead, RELAX NG opened its language. RELAX NG permits
foreign attributesattributes from any namespace other than the RELAX
NG namespaceto appear on all its elements...."
Going back to my XSLT example, with XSLT I can easily pick out all
elements with a given namespace or following a given pattern
with *a single template match*.
If you embedded the documentation using the mixed content schema as per
your example below, I can still pick it out but it will be a bit more
work. It will also be more brittle. If you add new deeply nested
elements or whatnot.. you see my point. In general with each change
to your schema I may have to go back and change my doco-generator xslt.
With namespaces, you rarely if ever have to make changes.
Perhaps the above is one of the reasons why namespaces are mentioned in
the Python mantra...
> > <z:directive>
> > <z:name>foo</z:name>
> > <a:documentation>
> > The foo directive indicates that the bar setting should be wombat.
> > This is important when...
> > </a:documentation>
> > </z:directive>
> what are the advantages of that approach over something like this:
> The foo directive indicates that the bar setting should be wombat.
> This is important when...
> I.e. just intermingle prose with the ZCML.
Zope3-dev mailing list