Re: [proposal] Cleaning up our component library
Geoff Howard wrote: Reinhard Poetz wrote: From: Sylvain Wallez [mailto:[EMAIL PROTECTED] The source-copy action already exists in o.a.c.acting.CopySourceAction, and the o.a.c.c.flow.util.PipelineUtil class could easily be generalized to any source, and not only cocoon:. Thanks for your answer and confirming that this would be a good idea. I don't have a use case yet (was just a thought I had when I read it) but if I have I'll implement it ;-) I implemented a first draft of something like this a month or so ago just for fun but may have lost it in a computer switch. I'll look for it and post/commit whatever I can find. Can't find what I was thinking of, so never mind... Geoff
RE: [proposal] Cleaning up our component library
From: Sylvain Wallez [mailto:[EMAIL PROTECTED] The source-copy action already exists in o.a.c.acting.CopySourceAction, and the o.a.c.c.flow.util.PipelineUtil class could easily be generalized to any source, and not only cocoon:. Thanks for your answer and confirming that this would be a good idea. I don't have a use case yet (was just a thought I had when I read it) but if I have I'll implement it ;-) -- Reinhard
Re: [proposal] Cleaning up our component library
Reinhard Poetz wrote: From: Sylvain Wallez [mailto:[EMAIL PROTECTED] The source-copy action already exists in o.a.c.acting.CopySourceAction, and the o.a.c.c.flow.util.PipelineUtil class could easily be generalized to any source, and not only cocoon:. Thanks for your answer and confirming that this would be a good idea. I don't have a use case yet (was just a thought I had when I read it) but if I have I'll implement it ;-) I implemented a first draft of something like this a month or so ago just for fun but may have lost it in a computer switch. I'll look for it and post/commit whatever I can find. Geoff
Re: [proposal] Cleaning up our component library
Le Mercredi, 28 jan 2004, à 02:40 Europe/Zurich, Joerg Heinicke a écrit : One problem often mentioned is that Cocoon provides to many possibilities to achieve some goals. Cocoon's flexibility ends where it is more confusing than helpful. Therefore I want to propose to remove/deprecate the components that are no longer the correct way to go, that are misleading by name or just don't do what their type of component is intended to do Sounds good, too many options do not help. ...Another example or the wrong components as [Read|Write]DOMSessionTransformer or SourceWritingTransformer. They are not transformers in the closer sense, they just tee the pipeline. They should be completely removed and replaced with either XModuleSource and aggregation (read) or FlowScript's processPipelineTo (write) Ok on the intention, but by removing these you force users to change their code, not only replace some components in the sitemap as you mention. I'm not sure about removing them unless they get in the way. ...I propose to deprecate those components in 2.1 and to remove them in 2.2... In cases where this just needs sitemap changes, no problem. But if deprecation requires code changes to existing applications we might want to move in smaller steps. How about: a) components marked deprecated log a warning when used (or when used for the first time) b) maybe add an option to throw an exception when such components are used (strict deprecation) c) deprecated components requiring code changes to user applications are kept in 2.2, unless keeping them is too much work. WDYT? -Bertrand
Re: [proposal] Cleaning up our component library
On Jan 28, 2004, at 8:43 AM, Ralph Goers wrote: We'd love to use Woody (aka Cocoon Forms), but if it can be used without FlowScript it isn't obvious. Woody and FlowScript should be totally independent from each other. Much of the fun stuff lately has been done in the JS utility library, but Woody itself doesn't require FlowScript - there's examples of using Woody with Actions at http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/woody/java/org/ apache/cocoon/woody/acting/ and http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/woody/java/org/ apache/cocoon/woody/samples/ /Steven -- Steven Noelshttp://outerthought.org/ Outerthought - Open Source Java XMLAn Orixo Member Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
Re: [proposal] Cleaning up our component library
Bertrand Delacretaz wrote: Le Mercredi, 28 jan 2004, à 02:40 Europe/Zurich, Joerg Heinicke a écrit : [...] ...I propose to deprecate those components in 2.1 and to remove them in 2.2... In cases where this just needs sitemap changes, no problem. But if deprecation requires code changes to existing applications we might want to move in smaller steps. How about: a) components marked deprecated log a warning when used (or when used for the first time) For the Lenya community it would be very helpful if the number of options was reduced (and I think this is also true for others). I'm not a real Cocoon committer, but very +1 for marking outdated components as deprecated. b) maybe add an option to throw an exception when such components are used (strict deprecation) This sounds very useful. There are some non-IDE users in our community who aren't that much aware of deprecation. Could it be switched on/off globally? -- Andreas
Re: [proposal] Cleaning up our component library
On 28.01.2004 10:55, Andreas Hartmann wrote: b) maybe add an option to throw an exception when such components are used (strict deprecation) This sounds very useful. There are some non-IDE users in our community who aren't that much aware of deprecation. Could it be switched on/off globally? Might be doable through a build system property. Strict deprecation would be on per default with a hint onto the property in the message, so that they can make their applications run again. Joerg
Re: [proposal] Cleaning up our component library
On 28.01.2004 07:52, Bertrand Delacretaz wrote: One problem often mentioned is that Cocoon provides to many possibilities to achieve some goals. Cocoon's flexibility ends where it is more confusing than helpful. Therefore I want to propose to remove/deprecate the components that are no longer the correct way to go, that are misleading by name or just don't do what their type of component is intended to do Sounds good, too many options do not help. ...Another example or the wrong components as [Read|Write]DOMSessionTransformer or SourceWritingTransformer. They are not transformers in the closer sense, they just tee the pipeline. They should be completely removed and replaced with either XModuleSource and aggregation (read) or FlowScript's processPipelineTo (write) Ok on the intention, but by removing these you force users to change their code, not only replace some components in the sitemap as you mention. I'm not sure about removing them unless they get in the way. You are right. I did not have the more than sitemap-changes in mind when thinking about the consequences. How about: a) components marked deprecated log a warning when used (or when used for the first time) b) maybe add an option to throw an exception when such components are used (strict deprecation) c) deprecated components requiring code changes to user applications are kept in 2.2, unless keeping them is too much work. WDYT? With our deprecated block we have another mean to lead the user to the new components. When it's excluded the application will just not work. But I don't know if this is true for 2.2 and real blocks too. 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). Joerg
RE: [proposal] Cleaning up our component library
From: Joerg Heinicke One problem often mentioned is that Cocoon provides to many possibilities to achieve some goals. Cocoon's flexibility ends where it is more confusing than helpful. Therefore I want to propose to remove/deprecate the components that are no longer the correct way to go, that are misleading by name or just don't do what their type of component is intended to do. I already asked the question for replacement when Daniel introduced the (X)ModuleSource's. The StreamGenerator reads from the stream - but that's not what the component generator is about. The difference between generators should not be the type of the sources, but the type of the content. The same is true for the FileGenerator. For those I propose a simple XMLGenerator as we have a HTMLGenerator. The type of the source is given by the source, i.e. @src. Furthermore the name FileGenerator is misleading as it reads from http: or cocoon: or any other XML source too. Another example or the wrong components as [Read|Write]DOMSessionTransformer or SourceWritingTransformer. They are not transformers in the closer sense, they just tee the pipeline. They should be completely removed and replaced with either XModuleSource and aggregation (read) or FlowScript's processPipelineTo (write). Similar as for the FileGenerator the DirectoryGenerator is out of date, we already have the replacement in our CVS. I guess there are some more components that does not meet their intention (seen from the component type's POV). I propose to deprecate those components in 2.1 and to remove them in 2.2. When the clear separation of concerns is more obvious than now (generation, aggregation, source, etc.) it will also be easier for the Cocoon users (especially new users) to dive into Cocoon and understand the principles of it. Therefore some backwards incompatibilities (it's not real incompatibility, but some components in the sitemap must be replaced when moving from 2.1 to 2.2) are the price to pay. I'm +1 to move the named components into the deprecated block because this perfectly signals your intentions and removing in 2.2 is okay for me because I think there will follow some more 2.1.x releases before we ship 2.2. -- Reinhard
RE: [proposal] Cleaning up our component library
Joerg Heinicke 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. 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). 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. Carsten
Re: [proposal] Cleaning up our component library
Carsten Ziegeler wrote: Joerg Heinicke 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. 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. 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. 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. Ditto. Vadim
RE: [proposal] Cleaning up our component library
Ralph Goers [EMAIL PROTECTED] writes: Our environment has special security concerns that just won't allow a scripting language - or even JSPs or XSPs for that matter. Ok, I'll bite; why single out scripting languages and dynamically produced pages? What about dynamically compiled Java? How about XSLts? It is just as easy to inject a security hole into a non-scripted language as a scripted one; perhaps easier since people rarely think to inspect the byte streams of the compiled code where as the source of the scripted language is all there is (assuming you trust the compilers and interpreters). Banning scripting on the client side I might understand. This however, seems like a very poorly thought out security policy; instead of determining what the real security exposures are a blanket decision was made to ban some very useful tools on the off chance they might be misused.
Re: [proposal] Cleaning up our component library
Vadim Gritsenko wrote: Carsten Ziegeler wrote: Joerg Heinicke 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. 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. 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. 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. 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. You mean to change SWT to an Action? 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. Ditto. 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). Geoff
RE: [proposal] Cleaning up our component library
From: Carsten Ziegeler Joerg Heinicke 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. +1 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). IIUC no flow but some input modules are the alternative here. 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. +1 -- Reinhard
RE: [proposal] Cleaning up our component library
I totally agree with this. I have focused totally on 2.1 in building our system. For things to suddenly be deprecated now would be most irritating. If 2.2 manages to make the process of building one's webapp easier with real blocks, a lot of folks like me will want to switch to it just for that. I really don't want to have to reimplement a bunch of stuff. -Original Message- From: Geoff Howard [mailto:[EMAIL PROTECTED] Sent: Wednesday, January 28, 2004 7:45 AM To: [EMAIL PROTECTED] Subject: Re: [proposal] Cleaning up our component library 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). Geoff
Re: [proposal] Cleaning up our component library
Geoff Howard wrote: Vadim Gritsenko wrote: 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. You mean to change SWT to an Action? I mean that there is already an action written to copy sources, if I'm not mistaken, which can copy one sosurce to another. Combined with cocoon protocol and all other protocols you can do a lot with it. But I'm not saying that I've analyzed all use cases and we should remove SWT. Some javadoc in SWT pointing to copy action (or other, more preferred, way) is the first step towards better use practices. Vadim
RE: [proposal] Cleaning up our component library
I thought actions were performed before generators and transformers? If so, how could an action copy data from a generator or transformer? Ralph -Original Message- From: Vadim Gritsenko [mailto:[EMAIL PROTECTED] Sent: Wednesday, January 28, 2004 8:11 AM To: [EMAIL PROTECTED] Subject: Re: [proposal] Cleaning up our component library I mean that there is already an action written to copy sources, if I'm not mistaken, which can copy one sosurce to another. Combined with cocoon protocol and all other protocols you can do a lot with it. But I'm not saying that I've analyzed all use cases and we should remove SWT. Some javadoc in SWT pointing to copy action (or other, more preferred, way) is the first step towards better use practices. Vadim
RE: [proposal] Cleaning up our component library
Joerg Heinicke [EMAIL PROTECTED] proposes: snip on discussion about components to be deprecated/ I propose to deprecate those components in 2.1 and to remove them in 2.2. Yes please! As Cocoon grows it gets harder and harder to see the real direction it is heading as long as it continues to carry with it every single experiment and work around that no longer makes sense. Housecleaning is a good thing
RE: [proposal] Cleaning up our component library
I'll admit that I didn't do the work evaluating Woody. My colleague indicated he had problems figuring out how to get Woody bindings to work without flow. If there are samples of that let me know and I'll have him look at it again. Thanks, Ralph -Original Message- From: Steven Noels [mailto:[EMAIL PROTECTED] Sent: Wednesday, January 28, 2004 12:30 AM To: [EMAIL PROTECTED] Subject: Re: [proposal] Cleaning up our component library On Jan 28, 2004, at 8:43 AM, Ralph Goers wrote: We'd love to use Woody (aka Cocoon Forms), but if it can be used without FlowScript it isn't obvious. Woody and FlowScript should be totally independent from each other. Much of the fun stuff lately has been done in the JS utility library, but Woody itself doesn't require FlowScript - there's examples of using Woody with Actions at http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/woody/java/org/ apache/cocoon/woody/acting/ and http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/woody/java/org/ apache/cocoon/woody/samples/ /Steven
Re: [proposal] Cleaning up our component library
Le Mercredi, 28 jan 2004, à 11:52 Europe/Zurich, Joerg Heinicke a écrit : ...With our deprecated block we have another mean to lead the user to the new components. When it's excluded the application will just not work. But I don't know if this is true for 2.2 and real blocks too... hmm...I don't like the idea of moving code around to deprecate it, what if a block has just one component that must be deprecated? Also, with CVS we lose code history when moving files around. Marking components with a marker interface would be less disruptive and easier to undo if (when) mistakes happen. Then the component manager could trigger log messages or exceptions (depending on the strict deprecation setting) when initializing the component. 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 ok but I agree with Carsten that renaming just because names aren't optimal does not make much sense. 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. ok 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). I was more thinking about a global strict deprecation setting, defaulting to false at first, but global. Either you leave it false to be able to use all components (with warnings) or you set it to true if you want to make sure your app doesn't use any deprecated stuff. -Bertrand
Re: [proposal] Cleaning up our component library
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). Thanks. 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 action. 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