blob: d4fcf359c64450e0d3cd6f510943bafb58860fcb [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>Upgrading to Apache Forrest 0.8-dev (v0.8-dev)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="../favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="../index.html">Welcome</a>
</li>
<li>
<a class="unselected" href="../contrib.html">Developers</a>
</li>
<li class="current">
<a class="selected" href="../versions/index.html">Versioned Docs</a>
</li>
<li>
<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
</li>
<li>
<a class="unselected" href="../tools/index.html">Tools</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs">
<a class="unselected" href="../docs_0_70/index.html">0.70 (current)</a><a class="selected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
</div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.80-dev</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_80/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/your-project.html">Using Forrest</a>
</div>
<div onclick="SwitchMenu('menu_selected_1.1.3', '../skin/')" id="menu_selected_1.1.3Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">How-To</div>
<div id="menu_selected_1.1.3" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_80/howto/index.html">Overview</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
<div id="menu_1.1.3.2" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
</div>
</div>
<div class="menupage">
<div class="menupagetitle">Upgrading to 0.8</div>
</div>
<div class="menuitem">
<a href="">Use Forrest</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Customize Forrest</div>
<div id="menu_1.1.3.5" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/sitemap-explain.html">Sitemaps explained</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-custom-html-source.html">Custom html source</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/project-sitemap.html">Project sitemap</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-corner-images.html">CSS corner SVG</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Integrate Forrest with tools</div>
<div id="menu_1.1.3.6" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/howto/howto-forrest-from-maven.html">Maven Integration</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/catalog.html">Using DTD Catalogs</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.3.7', '../skin/')" id="menu_1.1.3.7Title" class="menutitle">Extend Forrest</div>
<div id="menu_1.1.3.7" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/howto/howto-buildPlugin.html">Build a Plugin</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/skin-package.html">Package new Skins</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-asf-mirror.html">Download mirror</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3.9', '../skin/')" id="menu_1.1.3.9Title" class="menutitle">Adding Documentation</div>
<div id="menu_1.1.3.9" class="menuitemgroup">
<div class="menuitem">
<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3.9.2', '../skin/')" id="menu_1.1.3.9.2Title" class="menutitle">Multipage HowTo</div>
<div id="menu_1.1.3.9.2" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/howto/multi/howto-multi.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step1.html">Step 1</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step2.html">Step 2</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step3.html">Step 3</a>
</div>
</div>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/faq.html">FAQs</a>
</div>
<div onclick="SwitchMenu('menu_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div>
<div id="menu_1.1.5" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/linking.html">Menus and Linking</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/searching.html">Search Options in Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/locationmap.html">Locationmap</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/skins.html" title="About default skins, their naming and features">Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/status-themes.html">Dispatcher versus Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/cap.html">Sourcetype Action</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/validation.html">XML validation and entity resolution</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/changes.html">Changes</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/glossary.html">Glossary</a>
</div>
<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
<div id="menu_1.1.8" class="menuitemgroup">
<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
<div id="menu_1.1.8.1" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/dtd-docs.html">Overview</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
<div id="menu_1.1.8.2" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/document-v13.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.html">document-v20</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
<div id="menu_1.1.9" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/primer.html">Forrest Primer</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/libre-intro.html">Libre</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/dreams.html">Dream list</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
</div>
</div>
</div>
<div id="credit">
<hr>
This is documentation for development version v0.8
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<div title="Portable Document Format" class="pdflink">
<a class="dida" href="upgrading_08.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
<div class="trail">Font size:
&nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
&nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
&nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>Upgrading to Apache Forrest 0.8-dev</h1>
<div id="motd-area">
This is documentation for development version v0.8
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#introduction">Introduction</a>
</li>
<li>
<a href="#new">New Features</a>
</li>
<li>
<a href="#locationmaps">Locationmaps</a>
</li>
<li>
<a href="#modules">Forrest configuration simplification</a>
</li>
<li>
<a href="#clean">Run a clean target after upgrade</a>
</li>
<li>
<a href="#to2to">New filename convention for stylesheets</a>
</li>
<li>
<a href="#docs">Notes about documentation</a>
</li>
<li>
<a href="#cocoon">Notes about Cocoon version</a>
</li>
<li>
<a href="#xmlformat">Whitespace and indenting of xml files with xmlformat</a>
</li>
<li>
<a href="#tips">General upgrade tips</a>
</li>
<li>
<a href="#To+be+continued...">To be continued...</a>
</li>
</ul>
</div>
<a name="N1000D"></a><a name="introduction"></a>
<h2 class="underlined_10">Introduction</h2>
<div class="section">
<div class="note">
<div class="label">Note</div>
<div class="content">
This is the <strong>development</strong> version of Apache Forrest which
can be obtained from the Subversion repository or from a code snapshot.
See the notes for obtaining and <a href="../docs_0_80/howto/../build.html">Building
Forrest</a>.
</div>
</div>
<p>
This page describes some changes to Apache Forrest that affect people
who are upgrading to the 0.8 version. If you have other issues, then
please discuss on either the
<a href="../mail-lists.html#forrest-dev">dev</a> or
<a href="../mail-lists.html#forrest-user">user</a> mailing lists. As more
experience is gained, this document will be updated.
</p>
<p>
(If you are upgrading from a version prior to 0.7 then you will need to
see the notes for the previous upgrade.)
</p>
</div>
<a name="N1002C"></a><a name="new"></a>
<h2 class="underlined_10">New Features</h2>
<div class="section">
<p>
The following list shows some of the key new features. For the full list
of changes, see the main <a href="../docs_0_80/changes.html">change log</a> and also
for each plugin.
</p>
<ul>
<li>
<a href="../docs_0_80/locationmap.html">Locationmaps</a>.</li>
</ul>
<p>
Many new initial plugins are in the "whiteboard". See the entries in the
<a href="../docs_0_80/changes.html">change log</a> and see each plugin's
documentation and changes log. This includes the new Dispatcher. See
<a href="../docs_0_80/status-themes.html">Status of Themes: Skins and Dispatcher</a>.
</p>
</div>
<a name="N1004E"></a><a name="locationmaps"></a>
<h2 class="underlined_10">Locationmaps</h2>
<div class="section">
<p>
The <a href="../docs_0_80/locationmap.html">Locationmaps</a> define the mapping from
requests to locations which enables content and resources to be located
at various different sources.
</p>
<p>
Adding a default locationmap to your project is not required, but is
advisable. Sooner or later you will use it. Having a default one also
reduces the verbosity of the log files. Copy one from a fresh 'forrest
seed' to
<span class="codefrag">PROJECT_HOME/src/documentation/content/locationmap.xml</span>
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content">
If you do use locationmaps and an entry for a specific request is
missing Forrest generates a confusing error message. Please ask on our
mailing lists for help in debugging your problem (hint, turn on
locationmap debugging in
[FORREST_HOME]/main/webapp/WEB-INF/logkit.xconf, restart Forrest,
request the broken pages and visit
[SITE_HOM]/build/webapp/logs/locationmap.xml). This issue will be fixed
in the next version of Forrest.
</div>
</div>
</div>
<a name="N10065"></a><a name="modules"></a>
<h2 class="underlined_10">Forrest configuration simplification</h2>
<div class="section">
<p>
<strong>FOR-920</strong> Merging the <span class="codefrag">defaults</span> and
<span class="codefrag">project</span> modules to the new <span class="codefrag">properties</span> module.
You can use it like {properties:forrest.home}
</p>
<p>
In all custom code (e.g. project sitemaps or plugins) you need to do the
following:
</p>
<ul>
<li>find:
<span class="codefrag">{defaults:</span> and replace with
<span class="codefrag">{properties:forrest.</span>
</li>
<li>find:
<span class="codefrag">{forrest:</span> and replace with
<span class="codefrag">{forrest:forrest.</span> or
<span class="codefrag">{properties:forrest.</span> (if you do not need the
ChainMetaModule)</li>
<li>find:
<span class="codefrag">{project:</span> and replace with
<span class="codefrag">{properties:</span>
</li>
</ul>
</div>
<a name="N1009D"></a><a name="clean"></a>
<h2 class="underlined_10">Run a clean target after upgrade</h2>
<div class="section">
<p>
Do 'forrest clean-work' in each of your projects. This also removes the
old Cocoon disk cache.
</p>
</div>
<a name="N100A7"></a><a name="to2to"></a>
<h2 class="underlined_10">New filename convention for stylesheets</h2>
<div class="section">
<p>
There is now a filenaming convention for stylesheets (e.g.
document-to-html.xsl). This assists with automating the location of such
resources. See <a href="../docs_0_80/locationmap.html">Locationmap</a>.
</p>
<p>
For the default use of Forrest, this makes no difference. However, if
you have developed your own skin then you will need to do some filename
changes, e.g. <span class="codefrag">'cd skins/my-skin/xslt/html; mv tab2menu.xsl
tab-to-menu.xsl'</span> (do each of book2menu.xsl document2html.xsl
site2xhtml.xsl tab2menu.xsl). It is advisable to follow this naming
convention for your other resources, which will mean that you can
utilise the locationmap.
</p>
</div>
<a name="N100BB"></a><a name="docs"></a>
<h2 class="underlined_10">Notes about documentation</h2>
<div class="section">
<p>
After each release, the "Versioned Docs" are copied to form the new
"dev" set. Ideally the docs are then upgraded in readiness for the new
release. This has not been completed for the 0.8 release. In particular
there are example snippets of sitemaps which have not yet been upgraded
to reflect the changes to the sitemaps and the separation of some core
stuff into plugins. See issues
<a href="http://issues.apache.org/jira/browse/FOR-546">FOR-546</a> and
<a href="http://issues.apache.org/jira/browse/FOR-922">FOR-922</a> and
others.
</p>
</div>
<a name="N100CD"></a><a name="cocoon"></a>
<h2 class="underlined_10">Notes about Cocoon version</h2>
<div class="section">
<p>
The last time that we upgraded our packaged version of Cocoon trunk was
using their SVN r351990 on 2005-12-08. Since then a number of things
have happened to cause us to fall out of synchronisation with Cocoon.
There is various discussion about this in the Forrest and Cocoon dev
mail archives.
</p>
<p>
If you use your own version of Cocoon, then you will know about the
upgrade notes in the $FORREST_HOME/etc/cocoon_upgrade directory. You
might be able to advance a bit beyond the SVN revision, but not much.
Please help to rectify this situation.
</p>
</div>
<a name="N100DA"></a><a name="xmlformat"></a>
<h2 class="underlined_10">Whitespace and indenting of xml files with xmlformat</h2>
<div class="section">
<p>
All xml type files have been formatted using xmlformat. You can apply
this to your own work if necessary by using the same configuration as
the Forrest project. See notes at
<a href="http://issues.apache.org/jira/browse/FOR-644">FOR-644</a>.
</p>
</div>
<a name="N100E8"></a><a name="tips"></a>
<h2 class="underlined_10">General upgrade tips</h2>
<div class="section">
<p>
Synchronise your project's skinconf.xml and forrest.properties files.
</p>
<p>
Take advantage of the separation of concerns. In a new workspace, create
a fresh '<span class="codefrag">forrest seed</span>' site, then tweak its
forrest.properties and skinconf.xml until it reflects your old site.
When it is ready, replace your project's skinconf.xml and
forrest.properties files. Any remaining issues would concern other
aspects of your configuration, such as site.xml and your actual content.
</p>
</div>
<a name="N100F8"></a><a name="To+be+continued..."></a>
<h2 class="underlined_10">To be continued...</h2>
<div class="section">
<p>
...as more issues are discovered/remembered :) Please send feedback to
the <a href="../mail-lists.html#forrest-dev">mailing list</a>.
</p>
</div>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>