[Zope-dev] Re: [Zope-PTK] ZPatterns Documentation

[Steve Alexander]

"Phillip J. Eby" wrote:
> 
> Just comment, please, preferably in e-mail via Zope-dev.
> Thanks.

Generally very clear and helpful. Tomorrow, I'll try it out on someone
who hasn't been looking at ZPatterns a great deal, and see what she gets
from it.

A few suggestions. I feel sad that these seem to come across as
criticisms. Really, I'm very glad that you've found some time to work on
more accessible documentation.


You don't seem to say anything like "You make your own domain-specific
classes derive from DataSkin. These can be ZClasses or Python classes".
This may be obvious, but I think it is an important part of how data
skins are intended to be used.

"""A data manager helps data skins by:

Providing them access to their Data Plug-ins, including propagating
transaction events and DataManagementEvents to the Data Plug-ins"""

Still very jagon-filled. That's ok, if it is accompanied by some
real-world explanation.
Perhaps add something like "You can use Data plug-ins for indexing
Dataskins in a catalog, or in many catalogs, or [another different
familiar example]".

"""Keeping track of their canonical or "normalized" forms for
acquisition management"""

You almost lost me there :-)

"""Or, if a data skin is retrieved from any other Zope object, its
__of__ method will try to find a Customizer or "Folder With
Customization Support" in the acquisition path, then ask it for a data
manager to bind with. Once this is done, the skin remains bound to that
manager until the next such occurrence."""

Pretty clear, except the end -- next what occurrence? The next time the
data skin is retrieved from a Zope object? So, every time a dataskin is
retrieved from a zope object (that isn't a Rack), it uses acquisition to
look for a customizer.

--
Steve Alexander
Software Engineer
Cat-Box limited
http://www.cat-box.net