You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by je...@apache.org on 2003/09/08 14:22:51 UTC
cvs commit: xml-forrest/src/documentation/content/xdocs upgrading_05.xml site.xml
jefft 2003/09/08 05:22:51
Modified: src/documentation/content/xdocs site.xml
Added: src/documentation/content/xdocs upgrading_05.xml
Log:
Added a doc on upgrading to Forrest 0.5
Revision Changes Path
1.24 +4 -1 xml-forrest/src/documentation/content/xdocs/site.xml
Index: site.xml
===================================================================
RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/site.xml,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- site.xml 7 Sep 2003 04:59:38 -0000 1.23
+++ site.xml 8 Sep 2003 12:22:51 -0000 1.24
@@ -6,7 +6,9 @@
<license label="License" href="license.html"/>
<download label="Download" href="http://www.apache.org/dyn/closer.cgi/xml/forrest/"/>
<who label="Who we are" href="who.html"/>
- <faq label="FAQs" href="faq.html"/>
+ <faq label="FAQs" href="faq.html">
+ <ignoring_javadocs href="#ignoring_javadocs"/>
+ </faq>
<changes label="Changes" href="changes.html"/>
<todo label="Todo" href="todo.html"/>
<live-sites label="Live sites" href="live-sites.html"/>
@@ -37,6 +39,7 @@
<forrestbar label="The ForrestBar" href="forrestbar.html"/>
<forrestbot label="The Forrestbot" href="forrestbot.html"/>
<forrestbot-intro href="forrestbot-intro.html"/>
+ <upgrading_05 label="Upgrading to 0.5" href="upgrading_05.html"/>
</documentation>
<older_documentation label="Older Docs">
1.1 xml-forrest/src/documentation/content/xdocs/upgrading_05.xml
Index: upgrading_05.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
<document>
<header>
<title>Upgrading to Forrest 0.5</title>
<version>$Revision: 1.1 $</version>
<authors>
<person name="Jeff Turner" email="jefft@apache.org"/>
</authors>
</header>
<body>
<p>
This page describes changes to Forrest that affect people upgrading from 0.4 and earlier versions to 0.5. A full
list of changes is visible in the <link href="site:changes">changelog</link>. Please post your upgrade
experiences to the <link href="site:mail-lists/forrest-dev">forrest-dev mailing list</link>. As more experience is
gained, this document will be updated.
</p>
<section>
<title>Upgrading the sitemap</title>
<p>
In brief, Forrest 0.5 is <em>mostly</em> backwards-compatible for sites that do not define a custom sitemap.
Between 0.4 and 0.5, the Forrest sitemap was completely rewritten. Instead of a single sitemap.xmap doing
everything, a 'driver' sitemap.xmap now delegates to a number of mounted subsitemaps handling different functional
areas. The new sitemap is fully described in the <link href="ext:sitemap-ref">Sitemap Reference</link>.
</p>
<p>Users that have overridden and augmented the Forrest 0.4 sitemap.xmap will need to:</p>
<ol>
<li>Move their overridden sitemap (<code>src/documentation/sitemap.xmap</code>) out the way</li>
<li>Copy the new sitemap, $FORREST_HOME/context/sitemap.xmap, to <code>src/documentation</code></li>
<li>Reapply customizations to the new sitemap.xmap. Customizations can be determined by comparing the modified
sitemap.xmap with <link
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/conf/sitemap.xmap?rev=1.66&only_with_tag=FORREST_04">original
Forrest 0.4 sitemap</link>.</li>
</ol>
</section>
<section>
<title>Version-specific sitemaps</title>
<p>Forrest 0.5 now supports <em>version-specific sitemaps</em>. Ie., if your project's overridden sitemap is
called <code>sitemap-0.5.xmap</code>, then this sitemap will be used in preference to
<code>sitemap.xmap</code>, or any other sitemap-*.xmap variants.</p>
<p>So if, for example, one has:</p>
<source>
src/documentation/sitemap.xmap
src/documentation/sitemap-0.5.xmap
</source>
<p>Then Forrest 0.4 will use sitemap.xmap, and Forrest 0.5 will use sitemap-0.5.xmap. This means users don't
need to all upgrade to 0.5 at once.</p>
<p>As Forrest 0.5 has been split into multiple sitemaps, this version-specific behaviour is triggered for any
*-0.5.xmap file. For example, if one has:</p>
<source>
src/documentation/sitemap.xmap
src/documentation/forrest-0.5.xmap
</source>
<p>Then Forrest 0.4 will use sitemap.xmap, and Forrest 0.5 will use Forrest's own sitemap.xmap, plus the
user-defined forrest-0.5.xmap file.</p>
<p>The same system prevents future compatibility problems, so Forrest 0.5 should continue to work when future
(incompatible) sitemaps are present:</p>
<source>
src/documentation/sitemap.xmap
src/documentation/sitemap-0.5.xmap
src/documentation/sitemap-0.6.xmap
src/documentation/sitemap-0.7.xmap
</source>
<note>If your <code>forrest.properties</code> defines the
<code>forrest.validate.sitemap.{includes,excludes}</code> properties, these will have to be updated to prevent
validation of sitemaps from unused versions. If undefined, Forrest will only validate sitemaps from the
current version.</note>
</section>
<section>
<title>Excluding URLs: filterlinks.xsl removed</title>
<p>In Forrest 0.4, URLs could be excluded from command-line processing by overriding and editing
<code>filterlinks.xsl</code>, and excluding the link nodes. Forrest 0.5 uses the rewritten command-line from
Cocoon 2.1.1, which apart from being twice as fast, <strong>does not use filterlinks.xsl</strong>. Instead,
patterns for command-line inclusion and exclusion can be specified in cli.xconf, as described in <link
href="site:faq/ignoring_javadocs">this FAQ entry</link>.
</p>
</section>
<section>
<title>SVGs should omit DOCTYPE declarations</title>
<p>In Forrest 0.5, sites that render SVGs may encounter ClassCastExceptions:</p>
<source>
javax.xml.transform.TransformerException: java.lang.ClassCastException
at org.apache.xalan.transformer.TransformerImpl.transformNode(TransformerImpl.java:1326)
at org.apache.xalan.transformer.TransformerImpl.run(TransformerImpl.java:3329)
...</source>
<p>There appears to be a bug in Cocoon 2.1.1's SVG component where the DTD associated with SVGs cannot be
resolved. The workaround is to edit your <code>src/documentation/resources/images/*.svg</code> files, and
comment out the <strong><!DOCTYPE ... ></strong> declaration.</p>
</section>
<section>
<title>Skin invocation changes</title>
<p>Users with custom skins <em>may</em> need to update them, depending on what use they make of passed-in XSLT
parameters. If your custom skin does not appear to work with 0.5, look in Forrest's <code>sitemap.xmap</code>
for occurrences of <code>{forrest:skin}</code>, and check that the callee (your XSLT) is expecting what the
caller (the sitemap) is passing it. Forrest skins can be used as a reference.</p>
</section>
<section>
<title>To be continued...</title>
<p>..as more issues are discovered/remembered :) Please send feedback to the <link
href="site:mail-lists/forrest-dev">mailing list</link>.</p>
</section>
</body>
</document>