pipeline vs match

[Kamal <bh...@tt.com.au>]

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

[Kamal <bh...@tt.com.au>]

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

Re: pipeline vs match

[Joerg Heinicke <jo...@gmx.de>]

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