pipeline vs match
Hi, Something I have noticed about the Cocoon documentation is that the terms pipeline seems to be used to describe a map:match. For example: Sets the generator for the pipeline.[1] We know what is meant, but this could be very confusing for a newbie. Should we be using the term match here, perhaps with a link the description of map:match? I know historically, it is a pipeline. Cheers. PS. I have been adding the clearer descriptions to the various sitemap component found in the Cocoon 2.1 documentation. Are there any objections? [1] http://cocoon.zones.apache.org/daisy/cdocs/g1/g1/g2/g3/g1/850.html
Re: pipeline vs match
On 14.06.2008 09:06, Kamal wrote: Something I have noticed about the Cocoon documentation is that the terms pipeline seems to be used to describe a map:match. For example: Sets the generator for the pipeline.[1] We know what is meant, but this could be very confusing for a newbie. Should we be using the term match here, perhaps with a link the description of map:match? I know historically, it is a pipeline. Cheers. PS. I have been adding the clearer descriptions to the various sitemap component found in the Cocoon 2.1 documentation. Are there any objections? Yes, because it's wrong. It is a pipeline, not a match. A match is just similar to an if and has nothing to do with a pipeline as you can see in the following example: map:pipeline map:match map:generate/ map:transform/ map:match !-- executes 2nd transform only in certain cases -- map:transform/ /map:match map:serialize/ /map:match /map:pipeline or map:pipeline internal-only=true map:match map:generate/ map:transform/ /map:match map:match map:generate/ /map:match !-- ALL internal pipeline use XML serializer -- map:serialize type=xml/ /map:pipeline The confusion result from 2 facts: In most cases one complete pipeline is wrapped within one map:match statement. There is no obvious wrapping for the actual pipeline, map:pipeline seems to wrap multiple pipelines rather than one. But that's not quite true if you read it differently: A pipeline starts with the first generator that the treeprocessor comes along the path and ends with the first serializer. A map:match (just like an if) excludes a map:generate from certain paths to be found. Other examples: map:pipeline map:generate/ map:transform/ map:serialize/ map:match !-- will never be reached -- /map:match /map:pipeline The first combination of map:generate to map:serialize make the pipeline, map:match will never be reached. map:pipeline !-- different generator for different paths -- map:match pattern=path1 map:generate/ /map:match map:match pattern=path2 map:generate/ /map:match !-- same transformation -- map:transform/ map:match pattern=path1 map:serialize/ /map:match !-- path1 won't reach this, only path2 -- map:serialize/ /map:pipeline So technically map:pipeline IS the wrapper for a complete pipeline, because always only one pipeline will be constructed within it. It's just not that obvious. Disclaimer: The above examples should all work in Cocoon, but that does not mean I recommend to use them. The standard case of wrapping a pipeline within a map:match probably makes a sitemap more readable and useful than these examples to outline the concepts. Joerg
Re: pipeline vs match
Joerg Heinicke wrote: On 14.06.2008 09:06, Kamal wrote: Something I have noticed about the Cocoon documentation is that the terms pipeline seems to be used to describe a map:match. For example: Sets the generator for the pipeline.[1] We know what is meant, but this could be very confusing for a newbie. Should we be using the term match here, perhaps with a link the description of map:match? I know historically, it is a pipeline. Cheers. PS. I have been adding the clearer descriptions to the various sitemap component found in the Cocoon 2.1 documentation. Are there any objections? Yes, because it's wrong. It is a pipeline, not a match. A match is just similar to an if and has nothing to do with a pipeline as you can see in the following example: Sorry, forgot these cases. map:pipeline map:match map:generate/ map:transform/ map:match !-- executes 2nd transform only in certain cases -- map:transform/ /map:match map:serialize/ /map:match /map:pipeline or map:pipeline internal-only=true map:match map:generate/ map:transform/ /map:match map:match map:generate/ /map:match !-- ALL internal pipeline use XML serializer -- map:serialize type=xml/ /map:pipeline The confusion result from 2 facts: In most cases one complete pipeline is wrapped within one map:match statement. There is no obvious wrapping for the actual pipeline, map:pipeline seems to wrap multiple pipelines rather than one. But that's not quite true if you read it differently: A pipeline starts with the first generator that the treeprocessor comes along the path and ends with the first serializer. A map:match (just like an if) excludes a map:generate from certain paths to be found. Other examples: map:pipeline map:generate/ map:transform/ map:serialize/ map:match !-- will never be reached -- /map:match /map:pipeline The first combination of map:generate to map:serialize make the pipeline, map:match will never be reached. map:pipeline !-- different generator for different paths -- map:match pattern=path1 map:generate/ /map:match map:match pattern=path2 map:generate/ /map:match !-- same transformation -- map:transform/ map:match pattern=path1 map:serialize/ /map:match !-- path1 won't reach this, only path2 -- map:serialize/ /map:pipeline So technically map:pipeline IS the wrapper for a complete pipeline, because always only one pipeline will be constructed within it. It's just not that obvious. Disclaimer: The above examples should all work in Cocoon, but that does not mean I recommend to use them. The standard case of wrapping a pipeline within a map:match probably makes a sitemap more readable and useful than these examples to outline the concepts. Joerg
