Reinhard Poetz wrote:
Stefano Mazzocchi wrote:
Reinhard Poetz wrote:
Stefano Mazzocchi wrote:
Daniel Fagerstrom wrote:
[...]
Daniel,
let me repeat: I don't care about precision and elegance and
completeness, I care about usability.
I am thinking at flow users that want to use java components to do
their stuff. They should *NOT* care about
org.apache.cocoon.xml.XMLPipe.
Not all Cocoon users are flow users only ...
Reinhard, how many cocoon users have ever implemented
org.apache.cocoon.xml.XMLPipe?
My point is not about flow, is about brevity over completeness.
Stefano,
TBH I have no strong opinion whether XMLPipe should be part of the
public _documentation_. Of course it is part of the _public API_
because otherwise you're not able to implement e.g. a transformer, but
I'm sure that you know this as you're the author of this interface ;-)
I only doubt that the proposed way of how to find the classes and
interfaces, that should become part of the public documentation, will
lead to success. Do you guys really think that many people will start to
evaluate ~670 classes and interfaces? And if yes, Daniel, Vadim you and
me can't agree whether the interface XMLPipe is public or not. So I'm
not really optimistice about the outcome as we have to discuss the other
669 classes and interfaces too.
I'm just with Daniel that we should talk about the principles of what is
public and private first.
After agreeing on them one person can move the public interfaces and
classes into a seperate directoy and then we can create a cocoon-api.jar
and can create javadocs out of it.
If you or others think that the "wiki way" of tagging classes is more
successful (and faster), please go for it. Believe me, it's not my
intention to block this, especially as I don't have the time to work on
the alternative within the next 3-4 weeks.
Boy, this is getting frustrating.
I don't give a proverbial f*&k on how we do it the fact is that there
are many levels of "public API" and we are not acknoledging that,
nowhere something like this can be found.
In the past, we wanted FOM to be the only interface between flowscript
and the rest of the system but given how many services are embedded in
components and how many things were never added to FOM but just expected
to be discovered out of getComponent(), which means that you need to
know the entire cocoon internals to be able to write a simple
flowscript, which is totally ridiculous.
You want principles? here they are:
1) script-oriented people, those who don't know java and don't care,
those looking for RAD, those coming from the client or from the XML
world, should have a reduced API which includes FOM + useful components
+ environment API and no cocoon internals.
2) for power users, willing to extend cocoon, the cocoon internal APIs
(pipelines, caching, input modules, etc..)
3) for cocoon devepers, everything but at least packaged by block.
This is what I want.
I don't care if we do it by hand or we do it by javadoc or by other means.
I don't care if we use wikis or post-its to find out which interface
goes in which category(s), or if we use tags or even if we use embedded
RDF in the javadoc comments for it.
All I want is to help our users stick around... because honestly, I find
myself in the very uncomfortable position of suggesting people *NOT*TO*
use cocoon, because is such a horrible climb to get to that comfortable
plateau of productivity and this is honestly not acceptable today.
--
Stefano.
