[Zope3-dev] One namespace for ZCML

[Philipp von Weitershausen]

Jeff Shell wrote:
> Am I the only person who uses apidoc to look up what can be done with
> ZCML? Because honestly, finding out what directives are available and
> getting decent documentation about ZCML directives is the easiest
> thing in Zope 3. Understanding what's going on or what the real
> meaning of a particular value in combination with others might be -
> that's a different story. But finding out what namespaces are
> available and what the directives are has never been a problem. And I
> spend most of my apidoc time (when looking at ZCML) with the 'browser'
> and 'zope' nodes expanded. I rarely need the others ones.
>
> Less directives? Maybe. *
> Less "does a lot of things for you but offers no easy path to do some
> of the work yourself?" directives? Yes please.
> Less "similar to but varying by a couple of small details" directives?
> (browser:view and browser:page)? Yes please.

I find the subtle difference between browser:view and browser:page disturbing
There are also more things about them that I find very annoying. But that's
not the topic here... (see below)

> One namespace for everything? No thanks.

Yes, point is taken, the proposal has been retracted.

> Especially if the reason is
> "I don't like typing those namespaces at the top of the file."

Was never my point...


The following discussion really belongs into the other thread discussing my
"Reducing the amount of ZCML directives" proposal. I'll answer your points
now, but if you have detailed comments on just that proposal, then let's use
the other thread. This thread should be dead because I took everyone's point
and retracted the proposal (for now).

> * I don't mind directives that are easy to read by eye. Lumping
> everything into <utility> and <adapter> is not going to make things
> easier to read. I like <factory>. I like <browser:view>. I just
> wouldn't mind the documentation saying <browser:view...> is shorthand
> for ..., and can be done in pure Python and one line of ZCML by ....

It's not all about reading things. It's also about making a sense out of them.
If we'd just be looking at ZCML, then yes, nice and descriptive directive
names would be best. Looking at the bigger picture, we want people to
understand what they're doing. At least I myself prefer to understand what I'm
doing.

By the way, it's not only myself that I have in mind but also the one I'm
teaching about Zope. More consistency and less magic in ZCML would've made my
life a lot easier when writing the 1st edition of the book and giving
trainings to people...

> I'd also like to see documentation about when custom classes are
> created and why, and what to do if you don't want the ZCML to generate
> things for you.. It may have good reasons for generating things, I'd
> just like to know why. Because god knows, that's the code that I have
> the hardest time reading. (_discriminator this, handler_ that..).

There are no reasons for generating things. Cryptical things, should they
occur, can be tucked away in sensible base classes (the examples you bring
don't make any sense to me, but I give you as much that there *are* some
cryptical things).

The idea of making ZCML directives do less is explicitness, not unnecessary
verbosity. Creating stuff on the fly border magic. In case of
browser:page/browser:view it's much farther than just the border. FWIW, I
brainstormed on this in
http://www.z3lab.org/sections/blogs/philipp-weitershausen/2005_12_14_zcml-needs-to-do-less.
I'm currently evaluating some of those ideas, ammending them to what perhaps
could become a proposal... Not sure yet. Input is definitely welcome. In any
case I don't think the examples I'm giving are overly cryptic.

Philipp


----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.