Author: upayavira
Date: Mon Oct 11 04:58:46 2004
New Revision: 54567
Modified:
cocoon/trunk/src/documentation/xdocs/userdocs/transformers/sourcewriting-transformer.xml
Log:
tabs->spaces
Modified:
cocoon/trunk/src/documentation/xdocs/userdocs/transformers/sourcewriting-transformer.xml
==============================================================================
---
cocoon/trunk/src/documentation/xdocs/userdocs/transformers/sourcewriting-transformer.xml
(original)
+++
cocoon/trunk/src/documentation/xdocs/userdocs/transformers/sourcewriting-transformer.xml
Mon Oct 11 04:58:46 2004
@@ -17,188 +17,188 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"document-v10.dtd">
<document>
- <header>
- <title>Source Writing Transformer</title>
- <version>0.9</version>
- <type>Technical document</type>
- <authors>
- <person name="Jeremy Quinn" email="[EMAIL PROTECTED]"/>
- </authors>
- <abstract>This document describes the Source Writing
transformer of Cocoon.</abstract>
- </header>
- <body>
- <s1 title="Source Writing Transformer">
- <p>Diverts xml from a pipeline, writing it to a Source
(or
+ <header>
+ <title>Source Writing Transformer</title>
+ <version>0.9</version>
+ <type>Technical document</type>
+ <authors>
+ <person name="Jeremy Quinn" email="[EMAIL PROTECTED]"/>
+ </authors>
+ <abstract>This document describes the Source Writing transformer of
Cocoon.</abstract>
+ </header>
+ <body>
+ <s1 title="Source Writing Transformer">
+ <p>Diverts xml from a pipeline, writing it to a Source (or
deleting it).</p>
- <p>Thankfully, <code>FileSource</code> is no longer the
only <code>Source</code> that currently implements <code>WritableSource</code>;
there are implementations of WebDAV and Apache Slide WritableSources in the
scratchpad. Hopefully further <code>ModifiableSource</code> implementations
(XMLDB, CVS, Email, SQL, etc.) will be appear in the future.</p>
+ <p>Thankfully, <code>FileSource</code> is no longer the only
<code>Source</code> that currently implements <code>WritableSource</code>;
there are implementations of WebDAV and Apache Slide WritableSources in the
scratchpad. Hopefully further <code>ModifiableSource</code> implementations
(XMLDB, CVS, Email, SQL, etc.) will be appear in the future.</p>
<p>See the transformer in action with the Cocoon Samples for webdav
block,
and Wiki about it at
<link href="http://wiki.apache.org/cocoon/WebDAVCMS";>WebDAVCMS</link>.
</p>
- <ul>
- <li>Name : write-source</li>
- <li>Class:
org.apache.cocoon.transformation.SourceWritingTransformer</li>
- <li>Cacheable: no.</li>
- </ul>
- </s1>
- <s1 title="The Tags">
- <source>
- <![CDATA[
- <source:write>
- [<source:path/>]
- <source:source/>
- <source:fragment/>
- </source:write>
-
- <source:insert/>
- <source:path/>
- <source:source/>
- <source:fragment/>
- [<source:replace/>]
- [<source:reinsert/>]
- </source:insert>
+ <ul>
+ <li>Name : write-source</li>
+ <li>Class:
org.apache.cocoon.transformation.SourceWritingTransformer</li>
+ <li>Cacheable: no.</li>
+ </ul>
+ </s1>
+ <s1 title="The Tags">
+ <source>
+ <![CDATA[
+ <source:write>
+ [<source:path/>]
+ <source:source/>
+ <source:fragment/>
+ </source:write>
+
+ <source:insert/>
+ <source:path/>
+ <source:source/>
+ <source:fragment/>
+ [<source:replace/>]
+ [<source:reinsert/>]
+ </source:insert>
- <source:delete/>
- <source:source/>
- [<source:path/>] - Ignored
- [<source:fragment/>] - Ignored
- [<source:replace/>] - Ignored
- [<source:reinsert/>] - Ignored
- </source:insert>
- ]]>
- </source>
- <p>In the namespace
<code>xmlns:source="http://apache.org/cocoon/source/1.0";</code>.</p>
- <p>The contents of the
<code><![CDATA[<source:fragment/>]]></code>
+ <source:delete/>
+ <source:source/>
+ [<source:path/>] - Ignored
+ [<source:fragment/>] - Ignored
+ [<source:replace/>] - Ignored
+ [<source:reinsert/>] - Ignored
+ </source:insert>
+ ]]>
+ </source>
+ <p>In the namespace
<code>xmlns:source="http://apache.org/cocoon/source/1.0";</code>.</p>
+ <p>The contents of the <code><![CDATA[<source:fragment/>]]></code>
tag are written to the specified ModifiableSource when the
document containing it is transformed by SourceWritingTransformer
(or deleted if you are using the <code>delete </code>instruction).</p>
- </s1>
- <s1 title="Definition">
- <source>
- <![CDATA[
+ </s1>
+ <s1 title="Definition">
+ <source>
+ <![CDATA[
<map:transformer name="write-source"
src="org.apache.cocoon.transformation.SourceWritingTransformer">
- <map:parameter name="serializer" value="xml"/>
+ <map:parameter name="serializer" value="xml"/>
</map:transformer/>
- ]]>
- </source>
- <p>The SourceWritingTransformer is predefined for you
in the main SiteMap.</p>
- </s1>
- <s1 title="Invocation">
- <p>This invokes the SourceWritingTransformer on your
pipeline.</p>
- <source>
- <![CDATA[
+ ]]>
+ </source>
+ <p>The SourceWritingTransformer is predefined for you in the main
SiteMap.</p>
+ </s1>
+ <s1 title="Invocation">
+ <p>This invokes the SourceWritingTransformer on your pipeline.</p>
+ <source>
+ <![CDATA[
<map:transform type="write-source"/>
- ]]>
- </source>
- <p>Or you can over-ride the default serializer here.</p>
- <source>
- <![CDATA[
+ ]]>
+ </source>
+ <p>Or you can over-ride the default serializer here.</p>
+ <source>
+ <![CDATA[
<map:transform type="write-source">
<map:parameter name="serializer" value="my-special-serializer"/>
</map:transform>
- ]]>
- </source>
- </s1>
+ ]]>
+ </source>
+ </s1>
- <s1 title="The Tags in detail">
- <s2 title="source:write">
- <p>The source:write tag can take optional
attributes, <code>create</code> (defaults to 'true') and
<code>serializer</code> (defaults to the serializer set up in the definition or
invocation of the transformer).</p>
- <p>Replaces the entire content of a
<code>Source</code> (specified by the <code><![CDATA[<source:source/>]]></code>
tag) with the contents of the <code><![CDATA[<source:fragment/>]]></code> tag,
if @create is 'true', a new asset will be created if one does not already
exist.</p>
- <p>The
<code><![CDATA[<source:source/>]]></code> and
<code><![CDATA[<source:fragment/>]]></code> tags are required, a
<code><![CDATA[<source:path/>]]></code> tag is optional, if specified, the
value is used as an XPath to generate xml in your <code>Source</code>, in which
to wrap your content.</p>
- <s3 title="source:source">
- <p>The System ID of the
<code>Source</code> to be written to.</p>
- <p>e.g.
<code><![CDATA[<source:source>docs/blah.xml</source:source>]]></code> or
<code><![CDATA[<source:source>context:/blah.xml</source:source>]]></code>
etc.</p>
- </s3>
- <s3 title="source:fragment">
- <p>The XML Fragment to be written.</p>
- <p>For example:</p>
- <source>
- <![CDATA[
- <source:fragment><foo>
- <bar id="dogcow"/>
- </foo></source:fragment>
- ]]>
- </source>
- <p>or</p>
- <source>
- <![CDATA[
- <source:fragment>
- <foo/>
- <bar>
- <dogcow/>
- <bar/>
- </source:fragment>
- ]]>
- </source>
- <p>etc.</p>
+ <s1 title="The Tags in detail">
+ <s2 title="source:write">
+ <p>The source:write tag can take optional attributes,
<code>create</code> (defaults to 'true') and <code>serializer</code> (defaults
to the serializer set up in the definition or invocation of the
transformer).</p>
+ <p>Replaces the entire content of a <code>Source</code> (specified by
the <code><![CDATA[<source:source/>]]></code> tag) with the contents of the
<code><![CDATA[<source:fragment/>]]></code> tag, if @create is 'true', a new
asset will be created if one does not already exist.</p>
+ <p>The <code><![CDATA[<source:source/>]]></code> and
<code><![CDATA[<source:fragment/>]]></code> tags are required, a
<code><![CDATA[<source:path/>]]></code> tag is optional, if specified, the
value is used as an XPath to generate xml in your <code>Source</code>, in which
to wrap your content.</p>
+ <s3 title="source:source">
+ <p>The System ID of the <code>Source</code> to be written to.</p>
+ <p>e.g.
<code><![CDATA[<source:source>docs/blah.xml</source:source>]]></code> or
<code><![CDATA[<source:source>context:/blah.xml</source:source>]]></code>
etc.</p>
+ </s3>
+ <s3 title="source:fragment">
+ <p>The XML Fragment to be written.</p>
+ <p>For example:</p>
+ <source>
+ <![CDATA[
+ <source:fragment><foo>
+ <bar id="dogcow"/>
+ </foo></source:fragment>
+ ]]>
+ </source>
+ <p>or</p>
+ <source>
+ <![CDATA[
+ <source:fragment>
+ <foo/>
+ <bar>
+ <dogcow/>
+ <bar/>
+ </source:fragment>
+ ]]>
+ </source>
+ <p>etc.</p>
- <note>The second example type, can only
be used when the <code><![CDATA[<source:path/>]]></code> tag has been
specified.</note>
- </s3>
- <s3 title="source:path">
- <p>[Optional] XPath to specify how your
content is wrapped</p>
- <p>e.g.
<code><![CDATA[<source:path>doc</source:path>]]></code> - your content is
placed inside a <code><![CDATA[<doc/>]]></code> root tag.</p>
- <note>If this parameter is omitted,
your content MUST have only ONE top-level node.</note>
- </s3>
- </s2>
+ <note>The second example type, can only be used when the
<code><![CDATA[<source:path/>]]></code> tag has been specified.</note>
+ </s3>
+ <s3 title="source:path">
+ <p>[Optional] XPath to specify how your content is wrapped</p>
+ <p>e.g. <code><![CDATA[<source:path>doc</source:path>]]></code> -
your content is placed inside a <code><![CDATA[<doc/>]]></code> root tag.</p>
+ <note>If this parameter is omitted, your content MUST have only ONE
top-level node.</note>
+ </s3>
+ </s2>
- <s2 title="source:insert">
- <p>The source:insert tag can take optional
attributes, <code>create</code> (defaults to 'true') and
<code>serializer</code> (defaults to the serializer set up in the definition or
invocation of the transformer).</p>
- <p>Inserts into a <code>Source</code>
(specified by the <code><![CDATA[<source:source/>]]></code> tag) the contents
of the tag <code><![CDATA[<source:fragment/>]]></code> at the XPath location
specified in the <code><![CDATA[<source:path/>]]></code> tag, if @create is
'true', a new <code>Source</code> will be created if one does not already
exist.</p>
- <p>The
<code><![CDATA[<source:source/>]]></code>,
<code><![CDATA[<source:path/>]]></code> and
<code><![CDATA[<source:fragment/>]]></code> tags are all required, the
<code><![CDATA[<source:replace/>]]></code> and
<code><![CDATA[<source:reinsert/>]]></code> tags are optional.</p>
- <s3 title="source:source">
- <p>The System ID of the
<code>Source</code> to be inserted into.</p>
- <p>e.g.
<code><![CDATA[<source:source>docs/blah.xml</source:source>]]></code> or
<code><![CDATA[<source:source>context:/blah.xml</source:source>]]></code>
etc.</p>
- </s3>
- <s3 title="source:fragment">
- <p>The XML Fragment to be written.</p>
- <p>e.g.</p>
- <source>
- <![CDATA[
- <source:fragment>
- <foo>
- <bar id="dogcow"/>
- </foo>
- </source:fragment>
- ]]>
- </source>
- <p>or</p>
- <source>
- <![CDATA[
- <source:fragment>
- <foo/>
- <bar>
- <dogcow/>
- <bar/>
- </source:fragment>
- ]]>
- </source>
- <p>etc.</p>
- </s3>
- <s3 title="source:path">
- <p></p>
- </s3>
- <s3 title="source:replace">
- <p>[Optional] XPath (from
<code><![CDATA[<source:path/>]]></code>) to select the node that is replaced by
your new content</p>
- <p>e.g.
<code><![CDATA[<source:replace>foo/bar/dogcow/@status='cut'</source:replace>]]></code>
(is equivalent to this in XSLT:
<code>select="foo[bar/dogcow/@status='cut']"</code>), what gets replaced is the
<code><![CDATA[<foo/>]]></code> which has a <code><![CDATA[<bar/>]]></code>
with a <code><![CDATA[<dogcow status="cut"/>]]></code> in it.</p>
- <p>The <code>overwrite</code> attribute
of the parent <code><![CDATA[<source:insert/>]]></code> is used to check if
replacing is allowed. If <code>overwrite</code> is 'true' (the default) the
node is replaced. If <code>overwrite</code> is 'false' the node is only
inserted if the replace node is found.</p>
- </s3>
- <s3 title="source:reinsert">
- <p>[Optional] The XPath (relative to
<code><![CDATA[<source:replace/>]]></code>) to backup the contents of the
overwritten node to.</p>
- <p>e.g.
<code><![CDATA[<source:reinsert>foo/versions</source:reinsert>]]></code> or
<code><![CDATA[<source:reinsert>/doc/versions/foo</source:reinsert>]]></code>.</p>
- <p>If specified and a node is replaced,
all children of this replaced node will be reinserted at the given path.</p>
- </s3>
- </s2>
- <s2 title="Notes">
- <ul>
- <li>if 'replace' is not
specified, your 'fragment' is appended as a child of 'path'.</li>
- <li>if 'replace' is specified
and it exists and 'overwrite' is true, your 'fragment' is inserted in 'path',
before 'replace' and then 'replace' is deleted.</li>
- <li>if 'replace' is specified
and it exists and 'overwrite' is false, no action occurs.</li>
- <li>if 'replace' is specified
and it does not exist and 'overwrite' is true, your 'fragment' is appended as a
child of 'path'.</li>
- <li>if 'replace' is specified
and it does not exist and 'overwrite' is false, your 'fragment' is appended as
a child of 'path'.</li>
- <li>if 'reinsert' is specified
and it does not exist, no action occurs.</li>
- </ul>
- </s2>
+ <s2 title="source:insert">
+ <p>The source:insert tag can take optional attributes,
<code>create</code> (defaults to 'true') and <code>serializer</code> (defaults
to the serializer set up in the definition or invocation of the
transformer).</p>
+ <p>Inserts into a <code>Source</code> (specified by the
<code><![CDATA[<source:source/>]]></code> tag) the contents of the tag
<code><![CDATA[<source:fragment/>]]></code> at the XPath location specified in
the <code><![CDATA[<source:path/>]]></code> tag, if @create is 'true', a new
<code>Source</code> will be created if one does not already exist.</p>
+ <p>The <code><![CDATA[<source:source/>]]></code>,
<code><![CDATA[<source:path/>]]></code> and
<code><![CDATA[<source:fragment/>]]></code> tags are all required, the
<code><![CDATA[<source:replace/>]]></code> and
<code><![CDATA[<source:reinsert/>]]></code> tags are optional.</p>
+ <s3 title="source:source">
+ <p>The System ID of the <code>Source</code> to be inserted into.</p>
+ <p>e.g.
<code><![CDATA[<source:source>docs/blah.xml</source:source>]]></code> or
<code><![CDATA[<source:source>context:/blah.xml</source:source>]]></code>
etc.</p>
+ </s3>
+ <s3 title="source:fragment">
+ <p>The XML Fragment to be written.</p>
+ <p>e.g.</p>
+ <source>
+ <![CDATA[
+ <source:fragment>
+ <foo>
+ <bar id="dogcow"/>
+ </foo>
+ </source:fragment>
+ ]]>
+ </source>
+ <p>or</p>
+ <source>
+ <![CDATA[
+ <source:fragment>
+ <foo/>
+ <bar>
+ <dogcow/>
+ <bar/>
+ </source:fragment>
+ ]]>
+ </source>
+ <p>etc.</p>
+ </s3>
+ <s3 title="source:path">
+ <p></p>
+ </s3>
+ <s3 title="source:replace">
+ <p>[Optional] XPath (from <code><![CDATA[<source:path/>]]></code>)
to select the node that is replaced by your new content</p>
+ <p>e.g.
<code><![CDATA[<source:replace>foo/bar/dogcow/@status='cut'</source:replace>]]></code>
(is equivalent to this in XSLT:
<code>select="foo[bar/dogcow/@status='cut']"</code>), what gets replaced is the
<code><![CDATA[<foo/>]]></code> which has a <code><![CDATA[<bar/>]]></code>
with a <code><![CDATA[<dogcow status="cut"/>]]></code> in it.</p>
+ <p>The <code>overwrite</code> attribute of the parent
<code><![CDATA[<source:insert/>]]></code> is used to check if replacing is
allowed. If <code>overwrite</code> is 'true' (the default) the node is
replaced. If <code>overwrite</code> is 'false' the node is only inserted if the
replace node is found.</p>
+ </s3>
+ <s3 title="source:reinsert">
+ <p>[Optional] The XPath (relative to
<code><![CDATA[<source:replace/>]]></code>) to backup the contents of the
overwritten node to.</p>
+ <p>e.g.
<code><![CDATA[<source:reinsert>foo/versions</source:reinsert>]]></code> or
<code><![CDATA[<source:reinsert>/doc/versions/foo</source:reinsert>]]></code>.</p>
+ <p>If specified and a node is replaced, all children of this
replaced node will be reinserted at the given path.</p>
+ </s3>
+ </s2>
+ <s2 title="Notes">
+ <ul>
+ <li>if 'replace' is not specified, your 'fragment' is appended as
a child of 'path'.</li>
+ <li>if 'replace' is specified and it exists and 'overwrite' is
true, your 'fragment' is inserted in 'path', before 'replace' and then
'replace' is deleted.</li>
+ <li>if 'replace' is specified and it exists and 'overwrite' is
false, no action occurs.</li>
+ <li>if 'replace' is specified and it does not exist and
'overwrite' is true, your 'fragment' is appended as a child of 'path'.</li>
+ <li>if 'replace' is specified and it does not exist and
'overwrite' is false, your 'fragment' is appended as a child of 'path'.</li>
+ <li>if 'reinsert' is specified and it does not exist, no action
occurs.</li>
+ </ul>
+ </s2>
<s2 title="source:delete">
<p>This instruction takes only a
<code><![CDATA[<source:source/>]]></code>
parameter (as a child tag) and deletes the corresponding
@@ -209,12 +209,12 @@
you're set.
</p>
</s2>
- </s1>
-
- <s1 title="Examples">
- <s2 title="Simple Write">
- <source>
- <![CDATA[
+ </s1>
+
+ <s1 title="Examples">
+ <s2 title="Simple Write">
+ <source>
+ <![CDATA[
<page>
...
<source:write xmlns:source="http://apache.org/cocoon/source/1.0";>
@@ -228,12 +228,12 @@
</source:write>
...
</page>
- ]]>
- </source>
- </s2>
- <s2 title="Insert at end">
- <source>
- <![CDATA[
+ ]]>
+ </source>
+ </s2>
+ <s2 title="Insert at end">
+ <source>
+ <![CDATA[
<page>
...
<source:insert xmlns:source="http://apache.org/cocoon/source/1.0";>
@@ -246,12 +246,12 @@
</source:insert>
...
</page>
- ]]>
- </source>
- </s2>
- <s2 title="Replace">
- <source>
- <![CDATA[
+ ]]>
+ </source>
+ </s2>
+ <s2 title="Replace">
+ <source>
+ <![CDATA[
<page>
...
<source:insert xmlns:source="http://apache.org/cocoon/source/1.0";>
@@ -264,12 +264,12 @@
</source:insert>
...
</page>
- ]]>
- </source>
- </s2>
- <s2 title="Insert at the beginning">
- <source>
- <![CDATA[
+ ]]>
+ </source>
+ </s2>
+ <s2 title="Insert at the beginning">
+ <source>
+ <![CDATA[
<page>
...
<source:insert>
@@ -285,14 +285,14 @@
<source:insert>
...
</page>
- ]]>
- </source>
- <p>This sample does not currently work,
see the tests in the scratchpad at
<code>http://localhost:8080/cocoon/mount/editor/tests</code>.</p>
- <note>You must have built Cocoon with
the scratchpad included for this link to work.</note>
- </s2>
- <s2 title="Delete a source">
- <source>
- <![CDATA[
+ ]]>
+ </source>
+ <p>This sample does not currently work, see the tests in the
scratchpad at <code>http://localhost:8080/cocoon/mount/editor/tests</code>.</p>
+ <note>You must have built Cocoon with the scratchpad included for
this link to work.</note>
+ </s2>
+ <s2 title="Delete a source">
+ <source>
+ <![CDATA[
<page>
...
<source:delete>
@@ -300,14 +300,14 @@
<source:delete>
...
</page>
- ]]>
+ ]]>
</source>
</s2>
- <s2 title="Sample of the output of these tags">
- <p>This is the kind of information that the
<code>SourceWritingTransformer</code> outputs to the pipeline, replacing the
original <code>source:write</code> and <code>source:insert</code> tags</p>
- <source>
- <![CDATA[
+ <s2 title="Sample of the output of these tags">
+ <p>This is the kind of information that the
<code>SourceWritingTransformer</code> outputs to the pipeline, replacing the
original <code>source:write</code> and <code>source:insert</code> tags</p>
+ <source>
+ <![CDATA[
<page>
...
<sourceResult>
@@ -320,18 +320,18 @@
</sourceResult>
...
</page>
- ]]>
- </source>
- </s2>
- </s1>
- <s1 title="Known Problems">
- <p>Namespace handling: namespace declarations are not
copied to the <code>Source</code>, resulting in invalid XML.</p>
- <p>I cannot get the 'insert before' example working,
which uses the <code><![CDATA[<source:reinsert/>]]></code> tag.</p>
- </s1>
- <s1 title="Warning">
- <p>It is not known how robust this transformer is under
even moderate load, especially when it comes to more than one person modifying
the same file at the same time.</p>
- </s1>
- </body>
+ ]]>
+ </source>
+ </s2>
+ </s1>
+ <s1 title="Known Problems">
+ <p>Namespace handling: namespace declarations are not copied to the
<code>Source</code>, resulting in invalid XML.</p>
+ <p>I cannot get the 'insert before' example working, which uses the
<code><![CDATA[<source:reinsert/>]]></code> tag.</p>
+ </s1>
+ <s1 title="Warning">
+ <p>It is not known how robust this transformer is under even moderate
load, especially when it comes to more than one person modifying the same file
at the same time.</p>
+ </s1>
+ </body>
</document>
