shannon 02/05/13 10:55:25
Added: src/documentation/xdocs/faq README.txt book.xml
faq-configure-c2.xml faq-configure-environment.xml
faq-cvs.xml faq-databases.xml faq-debugging.xml
faq-install.xml faq-sitemap.xml faq-xslt.xml
index.xml
Log:
Initial faq setup for revised docs.
Preserves existing FAQ.dtd but breaks up
FAQ content by category to facilitate
processing of patches from user
contributions. This will most likely
be revised once FAQ dtd is discussed
in greater detail on Forrest.
Revision Changes Path
1.1 xml-cocoon2/src/documentation/xdocs/faq/README.txt
Index: README.txt
===================================================================
Filename conventions
FAQ files in this directory should follow the following naming convention:
faq-<descriptive-name-here>.xml
Use hyphens between any words which follow "faq-".
1.1 xml-cocoon2/src/documentation/xdocs/faq/book.xml
Index: book.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
"../dtd/book-cocoon-v10.dtd">
<book software="Apache Cocoon"
title="Apache Cocoon HOWTO Documentation"
copyright="@year@ The Apache Software Foundation">
<menu label="Navigation">
<menu-item label="Main" href="../index.html"/>
</menu>
<menu label="FAQs">
<menu-item label="Index" href="index.html"/>
</menu>
<menu label="Getting Started">
<menu-item label="Install" href="faq-install.html"/>
<menu-item label="Configure" href="faq-configure-environment.html"/>
</menu>
<menu label="Using">
<menu-item label="Configure C2" href="faq-configure-c2.html"/>
<menu-item label="Sitemap" href="faq-sitemap.html"/>
<menu-item label="Databases" href="faq-databases.html"/>
<menu-item label="XSLT" href="faq-xslt.html"/>
<menu-item label="Debugging" href="faq-debugging.html"/>
<menu-item label="CVS" href="faq-cvs.html"/>
</menu>
</book>
1.1 xml-cocoon2/src/documentation/xdocs/faq/faq-configure-c2.xml
Index: faq-configure-c2.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="Cocoon Configuration FAQs">
<faq>
<question>
How do i setup my own .roles file?
</question>
<answer>
<p>
In cocoon.xconf you can specify your my.roles file as follows:
</p>
<source><![CDATA[
...
<cocoon version="2.0" user-roles="WEB-INF/my.roles">
...
]]></source>
<p>
And create a new file my.roles in WEB-INF directory with
</p>
<source><![CDATA[
<?xml version="1.0"?>
<role-list>
<role name="org.apache.cocoon.components.jsp.JSPEngine"
shorthand="jsp-engine"
default-class="org.apache.cocoon.components.jsp.JSPEngineImplWLS"/>
</role-list>
]]></source>
</answer>
</faq>
<faq>
<question>
Where do i setup LogKit in Cocoon?
</question>
<answer>
<p>1. <code>{cocoon}/WEB-INF/logkit.xconf</code>:</p>
<p>Please refer to the Avalon Excalibur Documentation:
<link href="http://jakarta.apache.org/avalon/excalibur/logger.html";>
Avalon Excalibur LogKit Management</link></p>
<p>2. <code>{cocoon}/WEB-INF/web.xml</code>:</p>
<p>Here you can change following paramters:</p>
<ul>
<li><code>logkit-config</code>: This parameter indicates the configuration
file of the LogKit management</li>
<li><code>servlet-logger</code>: This parameter indicates the category id
of the logger from the LogKit configuration used by the CocoonServlet.</li>
<li><code>cocoon-logger</code>: This parameter indicates the category id of
the
logger from the LogKit management configuration for the Cocoon engine.
This logger is used for all components described in the cocoon.xconf
and sitemap.xmap file not having specified a logger with the
logger="..." attribute in the component configuration file.</li>
<li><code>log-level</code>: This parameter indicates the log level to use
throughout startup of the system. As soon as the logkit.xconf the setting
of the logkit.xconf configuration is used instead! Only for startup and if
the logkit.xconf is not readable/available this log level is of
importance.</li>
</ul>
<note>See inline comments in these files for further information!</note>
</answer>
</faq>
</faqs>
1.1
xml-cocoon2/src/documentation/xdocs/faq/faq-configure-environment.xml
Index: faq-configure-environment.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="Environment Configuration FAQs">
<faq>
<question>How could I have my Cocoon app in an URI other than
<you-server>/cocoon/<my-app>?
</question>
<answer>
<note> This entry refers only to an Apache + Tomcat + Cocoon configuration,
and was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon
2.0b1.
</note>
<p>Test whether Tomcat passes everything under the /cocoon context to
Cocoon. This may be tested by pointing your browser at
<your-server>:8080/cocoon/xsp/simple, if a text page named
"A simple XSP page", everything's fine.
</p>
<p>Now, suppose:</p>
<ol>
<li>you have a Cocoon application named "foo" which works fine when
called with <your-server>:8080/cocoon/foo
</li>
<li>you want the "foo" app to be called from
<your-server>:8080/foo instead.
</li>
</ol>
<p>The idea is just to redirect the desidered URI (foo) to the one within
the cocoon context (cocoon/foo).
</p>
<p>Since this has to be done before the URI is processed by Tomcat, it is
just natural to use Apache for this. And, of course the user should not
notice the redirection.
</p>
<p>Apache has an handy feature called mod_rewrite which does just this: URI
rewriting (see the "URL Rewriting Guide" in the Apache user's guide for
details).
</p>
<p>First of all, you should instruct Apache to load the mod_rewrite, hence,
you should add (on a Windows system) this line to the httpf.conf:
</p>
<source>LoadModule rewrite_module modules/ApacheModuleRewrite.dll</source>
<p>(by the way, most probably, this line is already on the httpd.conf, you
just have to un-comment it).
</p>
<p>Add this line to httpd.conf in order to activate mod_rewrite:</p>
<source>RewriteEngine On</source>
<p>It is highly recommended to use the logging option of mod_rewrite, in
order to check the correctness of the URI rewriting; just add this lines
to the httpd.conf:</p>
<source>
RewriteLog "C:/logs/rewrite.log"
RewriteLogLevel 9</source>
<p>The first line tells Apache to put the URI rewriting log in the
c:\logs\rewrite.log file (which happens to be on a Windows system, of
course). The second one tells Apache to record everything mod_rewrite
does, if you don't want to log anything, just set the RewriteLogLevel to
0.
</p>
<p>Now, it's time to do the URI rewriting trick:</p>
<source>RewriteRule foo/(.*) /cocoon/foo/$1 [PT]</source>
<p>This line instructs Apache to redirect everything under "foo" to
"cocoon/foo" and passes it on to other processing ("[PT]" option),
like mod_alias.
</p>
<p>Now, just restart Apache and point your browser to:</p>
<source><your-server>:8080/foo/<something>...</source>
<p>it should work just fine.</p>
</answer>
</faq>
<faq>
<question>How could I have my Cocoon app in a directory other than
$TOMCAT_HOME/webapps/cocoon/<my-app>?
</question>
<answer>
<note>This entry refers only to an Apache + Tomcat + Cocoon configuration,
and was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon
2.0b1.
</note>
<p>Let's suppose the following:</p>
<ol>
<li>you have an application called "foo" which works perfectly when
located under the %TOMCAT_HOME%\webapps\cocoon\foo directory.
</li>
<li>you want it to be located under the "c:\foo" directory instead</li>
</ol>
<p>This could be done pretty easily twisting a little bit the sitemap. The
idea is to mount the sub-sitemap of the "foo" application on a specific
location on the file system, rather than under the deafult cocoon context.
</p>
<p>Here's the sitemap.xmap fragment used to do this:</p>
<source><![CDATA[
<map:pipeline>
<map:match pattern="foo/**">
<map:mount uri-prefix="foo" src="file:///c:/foo/"/>
</map:match>
</map:pipeline>
]]></source>
<p>The "file:" type of source instructs Cocoon to search the sub-sitemap
under the specified directory (which happens to be "c:\foo", since this
is a Windows system). See explanation of
<link href="../userdocs/concepts/sitemap.html#file-url">file: URLs</link>
</p>
<p>Now, you just need to copy everything which was under the
webapps/cocoon/foo directory to the /foo directory, and it should work
graciously.
</p>
</answer>
</faq>
<faq>
<question>
How do I integrate Apache Server and Cocoon?
</question>
<answer>
<p>
You need to use mod_jk. Add the following line to
<code>%APACHE_HOME%\conf\httpd.conf</code>
</p>
<source>JkMount /cocoon/* ajp12</source>
<p>
along with other directives that are already listed in mod_jk.conf-auto
in the tomcat/conf directory. The the above directives can be added at the
end of httpd.conf.
</p>
</answer>
</faq>
<faq>
<question>
How do I hide "cocoon" in the URL's once I integrate using mod_jk as shown
above?
</question>
<answer>
<p>
Basically to use <code>http://your.server.org/Foo/welcome</code> (as an example)
instead of
<code>http://your.server.org/cocoon/Foo/welcome</code>. You need the following
two modifications:
</p>
<p>
Step #1: Add the following lies to to httpd.conf.
</p>
<source><![CDATA[
RewriteEngine On
RewriteLog "/var/log/rewrite.log"
RewriteLogLevel 0
RewriteRule ^/Foo /cocoon/Foo/ [R]
RewriteRule ^/Foo(.*) /cocoon/Foo$1 [R]
]]></source>
<p>
The file rewrite.log does not have to be located in <code>/var/log</code>. For
instance, under Windows NT other locations may be appropriate. The
RewriteLogLevel should be set 3 for debug purposes. The third line is
essentially a redirect, so that Foo becomee <code>/cocoon/Foo/</code> with the
trailing <code>/</code>, without it the request would not map onto
</p>
<source><![CDATA[
<map:match pattern="">
<map:redirect-to uri="welcome" />
</map:match>]]></source>
<p>
when you I request <code>http://your.server.org/Foo</code>.
Finally, the last RewriteRule could depend on the local settings.
The original suggestion by Luca was a single line entry (that replaces
both RewriteRules above) according to:
</p>
<source>RewriteRule Foo/(.*) /cocoon/Foo/$1 [PT]</source>
<note>
This did not work in my case (Slackware Linux with Apache1.3,
tomcat3.2.2, Cocoon). Again, these RewriteRules may vary somewhat
depending on the local settings. You may have to experiment a bit.
</note>
<p>
Step #2: Add to the sitemap.xmap in the cocoon directory.
</p>
<source><![CDATA[
<map:pipeline>
<map:match pattern="Foo/**">
<map:mount uri-prefix="Fru" src="file:///www/Foo/"
check-reload="yes" reload-method="synchron"/>
</map:match>
</map:pipeline>
]]></source>
<p>
Here, <code>/www/Foo</code> is a some directory on the local file system where
the
xml, xsp, .., files of the application Foo live.
</p>
</answer>
</faq>
<faq>
<question>
How can I run Cocoon without X11. Why is a Display needed?
</question>
<answer>
<p>
An Xserver is needed due to the batik library fop uses. batik uses
java's graphics code, which in turn requires the Xserver.
If you don't have an xserver on your system, and can't set the DISPLAY
variable to one, then try out xvfb. xvfb gives you an 'in-memory'
xserver, which doesn't require any display hardware to run.
</p>
<source><![CDATA[
$> Xvfb :1 -screen 0 800x600x8 &
$> export DISPLAY=:1
$> $TOMCAT_HOME/bin/startup.sh -f server.xml
]]></source>
<p>
Another solution is to use PJA library. Read 'Linux/Headless/Batik'
section in the <link href="../installing/index.html">Cocoon installation
guide</link>.
</p>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/src/documentation/xdocs/faq/faq-cvs.xml
Index: faq-cvs.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="CVS FAQs">
<faq>
<question>
How do I use the most recent CVS copy of the Cocoon code on my local system?
</question>
<answer>
<p>
This is described as a
<link href="../contrib.html#cvshowto">CVS Usage Precis</link> on the
Contribution page. It also explains how to get branches other than the
current HEAD branch.
</p>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/src/documentation/xdocs/faq/faq-databases.xml
Index: faq-databases.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="Database FAQs">
<faq>
<question>
When I try to use the Connection pooling code, I get the following exception:
"Could not get the datasource java.sql.SQLException: You cannot
get a Poolable before the pool is initialized". What's going on?
</question>
<answer>
<p>
The most common reason for this exception is that the driver was not loaded.
Cocoon uses an initial parameter in the "web.xml" file to automatically load
classes on startup. This way, the class is loaded only once and the server's
time is spent doing more productive things. Make sure the following entry
is in your "web.xml" file.
</p>
<source><![CDATA[
<init-param>
<param-name>load-class</param-name>
<param-value>
<!-- comma or whitespace separated list of fully
qualified class names to load on startup.
-->
oracle.jdbc.driver.OracleDriver
</param-value>
</init-param>
]]></source>
<p>
If the class is loaded correctly, and you are still getting this error, then
there
is probably an error in your connection information. The SQLException
above is thrown when there are no open connections to the database.
</p>
</answer>
</faq>
<faq>
<question>
The sql samples don't run.
</question>
<answer>
<p>
The sql samples are working when deploing the war file using the build
system:</p>
<source>
./build.sh \
-Dinclude.webapp.libs=yes \
-Dinstall.war=path/to/tomcat/webapps install
</source>
<p>
This command will take care of the path inside the configuration file to the
database resources.
</p>
</answer>
</faq>
<faq>
<question>
I've been able to run the database samples, but they don't run anymore.
</question>
<answer>
<p>
This happens when the servlet engine has been stopped abruptly (e.g. with
ctrl-C).
</p>
<p>
Hsqldb - the database used by C2 samples - is a single-process engine that
locks the database by setting the "modified" entry in
"WEB-INF/db/cocoondb.properties" to the value "yes" while some JDBC
connections exist.
</p>
<p>
With connection pooling, there's always some connections opened, and they're
not closed properly when you stop abruptly the servlet engine, so the database
stays in locked state and connections are refused at the next server startup.
</p>
<p>
To unlock the database, change manually "modified" to "no" in the
"cocoondb.properties"
before restarting the server.
</p>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/src/documentation/xdocs/faq/faq-debugging.xml
Index: faq-debugging.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="Debugging FAQs">
<faq>
<question>
How do I debug Cocoon using JDK1.3+?
</question>
<answer>
<p>
With JDK1.3, set the TOMCAT_OPTS (for Tomcat 3.X) or CATALINA_OPTS
(for Tomcat 4.X) as shown below (on Win2K) and then attach the debugger to
localhost:8000 using "<code>jdb -attach myhost:8000</code>" More information can
be found at
<link href="http://java.sun.com/j2se/1.3.0/docs/guide/jpda/conninv.html";>JPDA -
Connection and Invocation Details</link>.
</p>
<source><![CDATA[
set TOMCAT_OPTS=-classic -Xdebug -Xnoagent -Djava.compiler=NONE
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000
]]></source>
<note>
This method is supposed to work under JBuilder4.0 as well.
</note>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/src/documentation/xdocs/faq/faq-install.xml
Index: faq-install.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="Installation FAQs">
<faq>
<question>
Why doesn't anything happen when I access 'http://localhost/cocoon/'?
</question>
<answer>
<p>
You might want to check a few things.
</p>
<ul>
<li>
Is your server listening to port 80? If not, you have to call the right
port, for example, 'http://localhost:8080/cocoon/'. Note that Apache Tomcat
binds by default to port 8080, NOT 80.
</li>
<li>
Did your servlet engine install the WAR file? You can check this by making
sure the WAR file was unpacked or connecting to the administration tools
of your servlet engine.
</li>
<li>
If you didn't restart the servlet engine, do it.
</li>
</ul>
</answer>
</faq>
<faq>
<question>
Why does Cocoon take so long to start?
</question>
<answer>
<p>
Cocoon compiles sitemaps into java classes to increase runtime performance.
This occurs at startup only when the sitemap file is modified. For
all other requests, the compiled sitemap is executed.
<!-- See question #7
for information on how to pre-compile the sitemap and the XSP's.-->
</p>
</answer>
</faq>
<faq>
<question>
Why is cocoon.war so big?
</question>
<answer>
<p>
<!-- FIXME: isn't this pizza now -->
Cocoon.war includes all the libraries it requires to run. This includes
several megabytes of Java classes. It also includes the JDK javac compiler
which must be present in the war file to allow page compilation without
classloading problems.
</p>
</answer>
</faq>
<faq>
<question>
I get a java.lang.VerifyError when accessing 'http://localhost/cocoon/'.
What's wrong?
</question>
<answer>
<p>
Cocoon requires a JAXP 1.1 compliant parser. Some servlet engines
(like Tomcat 3.2.1) use older XML parsers. Replace the XML
parser with a more recnet one (e.g. the Xerces 1.3.0 or newer).
</p>
<p>
For Tomcat 3.2.1, remove the jaxp.jar and the parser.jar from the
tomcat/lib directory. Copy the xerces.jar to this directory and rename
it to parser.jar. Before you restart Tomcat, make sure to delete the
tomcat/work directory.
</p>
</answer>
</faq>
<faq>
<question>
Cocoon still won't start, this time I get
javax.xml.transform.TransformerConfigurationException: Namespace not supported by
SAXParser
in the Cocoon log file.
</question>
<answer>
<p>
This is a classloader issue with Tomcat and some other servlet engines.
Basically
it means that the Xerces library included with Cocoon is not being found. The
solution
is to place the Xerces library first in the classpath.
</p>
</answer>
</faq>
<faq>
<question>
Cocoon won't start, and I get a "java.lang.NoSuchMethodError:
org.apache.log.LogKit: method
createLogger(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lorg/apache/log/Logger;
not found" in my Servlet Container's log.
</question>
<answer>
<p>
You have an old set of libraries installed. Copy the correct libraries from the
distribution.
</p>
<p>
Even better, build Cocoon with "build -Dinclude.webapp.libs webapp". This build
creates a complete WAR file with all necessary libraries included.
</p>
</answer>
</faq>
<faq>
<question>
Windows 95/98 tells me that I don't have enough environment-memory.
</question>
<answer>
<p>
This is another neat feature from DOS- times.
To increase environment-space add the following line to your
config.sys (and restart):
shell=c:\command.com /E:4096 /P
</p>
</answer>
</faq>
<faq>
<question>
I'm still stuck, what do I do?
</question>
<answer>
<p>
Contact the Cocoon Users mail list ([EMAIL PROTECTED]).
Please do not contact developers directly for help. Cocoon users are
generally more responsive because they tend to have more experience than
developers
troubleshooting installation problems.
</p>
<p>
Cocoon has several log files which are stored in the context where you
installed
Cocoon. These logs are located in '{cocoon}/WEB-INF/logs/' where
{cocoon} is the context where Cocoon is installed. The
information contained in that file will help others help you.
</p>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/src/documentation/xdocs/faq/faq-sitemap.xml
Index: faq-sitemap.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="Sitemap FAQs">
<faq>
<question>
What are the steps to pre-compile the sitemap and XSP's?
</question>
<answer>
<ul>
<li>Set the auto-reload to false in your sitemap.xmap as follows:</li>
</ul>
<source><![CDATA[
<parameter name="auto-reload" value="false"/>
]]></source>
<ul>
<li>Use "-Dbuild.precompile=true" in your build command line when you are
building your WAR file.
</li>
</ul>
</answer>
</faq>
<faq>
<question>I don't want to hand edit the sitemap. Are there any
tools?</question>
<answer>
<p>Try <fork href="http://pollo.sourceforge.net/";>this</fork>
by Bruno Dumon.</p>
</answer>
</faq>
<faq>
<question>How do I create some content which isn't directly visible to
everyone?</question>
<answer>
<p>Put the content in an internal pipeline...</p>
<source><![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="int">
<map:generate src="docs/description.xml"/>
<map:serialize type="xml"/>
</map:match>
</map:pipeline>
<map:pipeline>
<map:match pattern="desc.html">
<map:generate src="cocoon:/int"/>
<map:transform src="stylesheets/description2html.xsl"/>
<map:serialize type="html"/>
</map:match>
</map:pipeline>
</map:pipelines>
]]></source>
</answer>
</faq>
<faq>
<question>How can I concatenate two xml files?</question>
<answer>
<source><![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="one">
<map:generate src="docs/one.xml"/>
<map:serialize type="xml"/>
</map:match>
<map:match pattern="two">
<map:generate src="docs/two.xml"/>
<map:serialize type="xml"/>
</map:match>
</map:pipeline>
<map:pipeline>
<map:match pattern="desc.html">
<map:aggregate element="newRootElement">
<map:part src="cocoon:/one" element="firstXMLfile"/>
<map:part src="cocoon:/two" element="secondXMLfile"/>
</map:aggregate>
<map:transform src="stylesheets/merge2html.xsl"/>
<map:serialize type="html"/>
</map:match>
</map:pipeline>
</map:pipelines>
]]></source>
<p>Where the element attribute names are replaced with something more
meaningful! Note that the map:part element attributes can be left off,
which results in the two parts being placed one immediately after the
other.</p>
</answer>
</faq>
<faq>
<question>I want to use the XXX matcher/serializer/selecter/etc but there's no
examples :(</question>
<answer>
<p>If you've checked the sample webapps which come with Cocoon, and you've
looked in the documentation, then check both the user and
dev archives. If it hasn't been resolved before <strong>first</strong>
email the user group and, after a <strong>reasonable</strong> (ie 1 or 2
days) length of time (remember not everyone lives in your timezone) email
the dev group.</p>
<p>Please don't cross-post to both the user and dev groups - very few people
like getting bombarded!</p>
<p>Oh, and once you do get it working - how about documenting it and
contributing it back to the group?</p>
</answer>
</faq>
<faq>
<question>When I add an action to a pipeline Cocoon returns an
error.</question>
<answer>
<p>Before the action was added to the pipeline it worked fine. After
the change Cocoon seems not to find the file specified in the
variable that is returned by the matcher.</p>
<source><![CDATA[
<map:match pattern="*">
<map:act type="validate-session">
<map:generate type="serverpages" src="{../1}.xsp"/>
</map:act>
<map:serialize/>
</map:match>
]]></source>
<p>Please note in the above example the
"<em><code>../1</code></em>".</p>
<p>Map objects returned from matchers, actions etc. are organised
<em>hierarchically</em>. Therefore they are not replaced by new ones
but older ones are still accessible through a path expression. Here
"<code>../1</code>" references key ("variable") "1" in the next to
last Map. </p>
</answer>
</faq>
<faq>
<question>
I changed the sitemap, but my changes don't show in the browser.
Do I need to restart the servlet container?
</question>
<answer>
<p>Cocoon lets you decide whether it needs to poll for sitemap changes
(with its associated performance penalty) or not. It also lets you decide
whether the re-compilation resulting from polling shoud happen in the
background or in the foreground.</p>
<p>If you look at the cocoon.xconf file, you'll notice this element:</p>
<source><![CDATA[
<sitemap file="sitemap.xmap"
reload-method="asynchron"
check-reload="yes"/>]]></source>
<p>Which means:</p>
<ul>
<li>The <code>check-reload</code> attribute determines if the sitemap
is reloaded on change. Set to "no", the sitemap is generated once
at startup. Set to "yes", the sitemap is regenerated if it changes.</li>
<li>The <code>reload-method</code> specifies the method for the
regeneration:
<ol>
<li><code>asynchron</code>: If the sitemap changes, the sitemap is
regenerated at the next request in the background and the incoming
request is served with the old sitemap. All subsequent requests
are served with the old sitemap until the regeneration in the
background has finished.</li>
<li><code>synchron</code>: If the sitemap changes, the sitemap
is regenerated at the next request. When the regeneration is
finished, the request (and all subsequent ones) is served with
the new sitemap.</li>
</ol>
</li>
</ul>
<p>
For a development environment, set the reload-method to "synchron" and the
check-reload to "yes." For a production environment,
set the reload-method to "asynchron." For more safety, set the check-reload
to "no."
</p>
<p>In a nuthsell: By default, reload is "asynchron" which means:</p>
<ol>
<li>Change sitemap</li>
<li>Hit reload</li>
<li>Wait while CPU goes up to 100% and back down to 0%</li>
<li>Hit reload</li>
<li>Voila - new sitemap is used! :)</li>
</ol>
<p>Hence: you don't need to restart the servlet container.</p>
<p>For sub-sitemaps, this issue is defined in the mounting element:</p>
<source><![CDATA[
<map:mount uri-prefix="foo" src="file:///c:/foo/"
check-reload="yes"
reload-method="synchron"/>]]></source>
<p>With these settings Cocoon will react to any changes in the sub-sitemap,
without even hitting the reload button twice. :)</p>
<p>
Moreover, it is a good idea to use sub-sitemaps because they reduce
overall compilation time. For example, changes to a single sub-sitemap won't
require recompilation for the the main sitemap or other sub-sitemaps. This
practice leads to greater degree of modularity.
</p>
</answer>
</faq>
<faq>
<question>How do I create some content which isn't directly visible to
everyone?</question>
<answer>
<p>Put the content in an internal pipeline...</p>
<source><![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="int">
<map:generate src="docs/description.xml"/>
<map:serialize type="xml"/>
</map:match>
</map:pipeline>
<map:pipeline>
<map:match pattern="desc.html">
<map:generate src="cocoon:/int"/>
<map:transform src="stylesheets/description2html.xsl"/>
<map:serialize type="html"/>
</map:match>
</map:pipeline>
</map:pipelines>
]]></source>
</answer>
</faq>
<faq>
<question>How can I concatenate two XML files?</question>
<answer>
<source><![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="one">
<map:generate src="docs/one.xml"/>
<map:serialize type="xml"/>
</map:match>
<map:match pattern="two">
<map:generate src="docs/two.xml"/>
<map:serialize type="xml"/>
</map:match>
</map:pipeline>
<map:pipeline>
<map:match pattern="desc.html">
<map:aggregate element="newRootElement">
<map:part src="cocoon:/one" element="firstXMLfile"/>
<map:part src="cocoon:/two" element="secondXMLfile"/>
</map:aggregate>
<map:transform src="stylesheets/merge2html.xsl"/>
<map:serialize type="html"/>
</map:match>
</map:pipeline>
</map:pipelines>
]]></source>
<p>Replace the element attribute names with something more
meaningful! Note that the map:part element attributes can be ommitted,
which results in the two parts being placed one immediately after the
other.</p>
</answer>
</faq>
<faq>
<question>I want to use the XXX matcher/serializer/selecter/etc but there's no
examples. :(</question>
<answer>
<p>Check the sample webapps which come with Cocoon. Review the documentation.
Check both the cocoon-users and cocoon-dev list archives. If it hasn't been
resolved before, <strong>first</strong>
email cocoon-users and, after a <strong>reasonable</strong> (i.e. one or two
days) length of time (remember not everyone lives in your timezone) email
the cocoon-dev list.</p>
<p>Please don't cross-post to both the user and dev groups. Very few people
like getting bombarded!</p>
<p>Oh, and once you do get it working, how about documenting it and
contributing it back to the community?</p>
</answer>
</faq>
<faq>
<question>When I add an action to a pipeline Cocoon returns an
error.</question>
<answer>
<p>Before the action was added to the pipeline it worked fine. After
the change Cocoon seems not to find the file specified in the
variable that is returned by the matcher.</p>
<source><![CDATA[
<map:match pattern="*">
<map:act type="validate-session">
<map:generate type="serverpages" src="{../1}.xsp"/>
</map:act>
<map:serialize/>
</map:match>
]]></source>
<p>Please note in the above example the
"<em><code>../1</code></em>".</p>
<p>Map objects returned from matchers, actions etc. are organised
<em>hierarchically</em>. Therefore they are not replaced by new ones
but older ones are still accessible through a path expression. Here
"<code>../1</code>" references key ("variable") "1" in the next to
last Map. </p>
</answer>
</faq>
<faq>
<question>
What is the syntax for absolute filesystem pathnames.
</question>
<answer>
<p>
In your sitemaps you may need to refer to some resource that is outside
the webapp context (e.g. UNIX /foo/bar/this.xsl
e.g. Windows C:\foo\bar\this.xsl). You need to use the file: convention.
</p>
<ul>
<li>UNIX ... <code>file:///foo/bar/this.xsl</code></li>
<li>Windows ... <code>file:///C:/foo/bar/this.xsl</code></li>
</ul>
<p>
See further explanation of
<link href="../userdocs/concepts/sitemap.html#file-url">file: URLs</link>
</p>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/src/documentation/xdocs/faq/faq-xslt.xml
Index: faq-xslt.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">
<faqs title="XSLT FAQs">
<faq>
<question>
How do I tell Cocoon to stop adding carriage-returns during XSL
transformation?
</question>
<answer>
<p>The short answer is that this is not a Cocoon issue. You need to
read up on XSLT usage. Please see
<link href="../mail-lists.html">other resources for XSLT,</link>
specifically, the XSL FAQ and discussion lists.
</p>
<p>The long answer is that you need to use the XSLT function
<code>normalize-space()</code> whenever you want to rely on the content
of an xml element.
</p>
<p>For example, if your application is producing some Javascript code in
your HTML output, then you might mistakenly try to use the following
construct in your XSL stylesheet:
</p>
<source><![CDATA[
alert('<xsl:value-of select="message"/>');
]]></source>
<p>which will produce:</p>
<source><![CDATA[
alert('
messageValue
');
]]></source>
<p>The line-endings in the content of your "<code>message</code>"
element will cause javascript errors. Instead, do this:
</p>
<source><![CDATA[
alert('<xsl:value-of select="normalize-space(message)"/>');
]]></source>
<p>Note that there are many more issues about whitespace handling. Please
refer to the relevant XSLT resources rather than clutter up the Cocoon
discussion lists.
</p>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/src/documentation/xdocs/faq/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>Cocoon FAQs</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Diana Shannon" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
This is a collection of FAQs. The Cocooon project is actively seeking additional FAQ
contributors to expand this collection. For information on how to write your own FAQ,
please see <link href="../howto/howto-author-faq.html">How to Write your own
FAQ.</link>
</p>
</s1>
<s1 title="FAQs">
<s2 title="Getting Started">
<ul>
<li><link href="faq-install.html">Installing Cocoon</link></li>
<li><link href="faq-configure-environment.html">Configuring the Cocoon
Environment</link></li>
</ul>
</s2>
<s2 title="Using Cocoon">
<ul>
<li><link href="faq-configure-c2.html">Configuring Cocoon</link></li>
<li><link href="faq-sitemap.html">Sitemap</link></li>
<li><link href="faq-databases.html">Databases</link></li>
<li><link href="faq-xslt.html">XSLT</link></li>
<li><link href="faq-debugging.html">Debugging</link></li>
<li><link href="faq-cvs.html">CVS</link></li>
</ul>
</s2>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
