cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joerg Heinicke <>
Subject Re: [proposal] Cleaning up our component library
Date Wed, 28 Jan 2004 23:59:42 GMT
On 28.01.2004 16:44, Geoff Howard wrote:

>>>> So alltogether:
>>>> a) Components that are just renamed or replaced with only sitemap 
>>>> changes (FileGenerator => XMLGenerator, DirectoryGenerator => 
>>>> TraversableGenerator (or however it is called ;-) ), StreamGenerator 
>>>> => XMLGenerator + ModuleSource) are deprecated in 2.1 and removed in 
>>>> 2.2.
>>>> b) Components that need "real" application changes as 
>>>> processPipelineTo or anything similar are also deprecated in 2.1, 
>>>> but will be kept in 2.2.
>>>> c) Deprecation messages:
>>>> Strict deprecation for a) components. 80% are catched by "file" => 
>>>> "xml" and "file" is the default generator and "xml" will be it.
>>>> Loose deprecation with a warning on every usage (otherwise they are 
>>>> to easily lost in the logs) for b) components. If we also use strict 
>>>> deprecation here, we don't really need b).
>>> Some general notes:
>>> I think whatever we do in this area, we should make a vote for each 
>>> change.
>> Totally agree. Please do not make such changes without voting first on 
>> each change.

Hey, of course! I never had in mind to "just change it".

>> For example, I already have objectsion against renaming File / 
>> Directory Generators - those are the most intuitive / easy-to-use 
>> components we have today. File and Directory abstractions are well 
>> known throughout the computing world (including non-English speakers); 
>> and File / Directory does not have to be on the file system, they 
>> could be anywhere: WebDAV, XML:DB, etc.
>> OTOH, TraversableGenerator is just *horrible* name.

Ok, I can go with you with the DirectoryGenerator. The only problem here 
is that it is bound to the file system at the moment. We have the 
TraversableGenerator in our CVS, which is the more generic 
implementation, but with a bad name. We had already discussions on its 
name like HierarchyGenerator. I could also imagine to just replace the 
DirectoryGenerator with the TraversableGenerator and name the TG as DG.

But it's another point with the FileGenerator. While the abstraction of 
file might be ok, you just can not read text or html files, but only XML.

> I am sort of one the fence here.  I agree with the premise that our 
> names are misleading in many cases.  However, I think mass confusion may 
> ensue if we rename mainstay components like the FileGenerator.  Of 
> course, we can move the real implementation to an XMLGenerator and make 
> FileGenerator extend it, deprecating FileGenerator.

That's a good compromise IMO.

> I wonder if we should move much more slowly on the removal end, focus on 
> better naming conventions moving forward, and provide a very clear 
> documentation explaining the paradox (e.g., "File" generator really 
> works with  any source which is already unparsed XML at its nature, if 
> an appropriate Source exists to get at it).  As people have been free to 
> subclass any existing generator, I don't know how we can expect any real 
> renaming to be "sitemap only".

Subclassing is a good point. I only wonder if there is so much subclassed.

> Now, I say that mostly with the users list in mind and I defer to your 
> (Joerg's) opinion greatly about that.  (for devs unsubscribed on the 
> users list, Joerg is absolutely indispensable there, IMO).


>>> And we should only move things into the deprecated part if there is a
>>> usable alternative. IMHO, using flow instead of a transformer isn't 
>>> really
>>> an alternative as the overhead is way to much (just my opinion here).
>> -1 to replacing of SourceWritingTransformer with the flosw. It's name 
>> is a bit misleading, and SourceCopyAction sounds better to me, but any 
>> alternative to SWT must be non-flow.

Ok, I see. Flow is not an option, but a component like the propagated 

>>> And we should avoid the renaming trap - which means renaming things just
>>> because a "not so perfect" name has been chosen in the first place. IMHO
>>> there is no real use in this.

But if the name is just wrong there is a real use. Also the renaming 
from File to XML would make it much more consistent as we have a 
HTMLGenerator, TextGenerator, MidiGenerator, JSPGenerator and so on. 
They all are files, but could not be read by FileGenerator. The core 
point of this generator is XML, not file.

> I sympathize with this too.  The amount of documentation, (cvs, wiki, 
> books, other external) that would become outdated scares me here.  The 
> naming is confusing, but not as confusing as inaccurate docs.
> What about doing "weak" deprecation, with good explanation that the move 
> is in name only.  INFO level logging on each use seems reasonable.  But 
> I'd propose that since this would come late in the 2.1 cycle that 
> removing in 2.2 is too soon.  I'd propose continue deprecation in 2.2 
> and remove only after that - maybe even a major version (i.e., 3.0).

I understand your concerns about confusing users. But at the moment I 
see much more confusion for new users. Users that already know Cocoon 
and have to change their application because of my proposed changes know 
what they are doing, it's just a question of informing them 
appropriately. But new users don't see the concepts as they are no 
longer clear. The main concept is Separation of Concerns (something like 
a definitive argument :) ) and if we document this separation it will be 
much easier to dive into Cocoon. But the components must reflect this 
separation. If a transformer writes something to DOM or disc then it's 
just wrong. This is the task of the controller.

The other point is time. I understand that 2.2 is a way to fast for 
removing/replacing components. But how long will you go with 
old/wrong/irritatingly named stuff just for compatibility reasons? I 
like Geoff's proposal of doing the final step (removing) with the next 
major version 3.0. Before we will have weak (2.1 and 2.2) and strict 
(2.3, ...) deprecation. This is only the general way to go and we will 
vote about it for every component individually.

Does this address all of your concerns? WDYT?


View raw message