forrest-site-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r1068306 [22/22] - in /forrest/site: docs_0_100/ docs_0_100/howto/ docs_0_100/howto/cvs-ssh/ docs_0_100/howto/multi/ docs_0_100/images/ pluginDocs/plugins_0_100/ trash/ trash/docs_0_50/ trash/docs_0_70/
Date Tue, 08 Feb 2011 09:44:48 GMT
Added: forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html
URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html (added)
+++ forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html Tue Feb  8 09:44:46 2011
@@ -0,0 +1,515 @@
+<!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.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Plugin Infrastructure (v0.10-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 Software Foundation</a> &gt; <a href="http://forrest.apache.org/">Apache 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>
+<a class="unselected" href="../../versions/index.html">Versioned Docs</a>
+</li>
+<li class="current">
+<a class="selected" 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="../../pluginDocs/plugins_0_90/index.html">0.90 (current)</a><a class="selected" href="../../pluginDocs/plugins_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../../pluginDocs/plugins_0_80/index.html">0.80 (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.100 Plugins</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../pluginDocs/plugins_0_100/index.html">Index</a>
+</div>
+<div class="menuitem">
+<a href="../../pluginDocs/plugins_0_100/usingPlugins.html">Using Plugins</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Plugin Infrastructure</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+        This is documentation for development version v0.10-dev
+       (<a href="http://forrest.apache.org/pluginDocs/">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://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+<!--+
+    |end Menu
+    +-->
+<!--+
+    |start content
+    +-->
+<div id="content">
+<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>Plugin Infrastructure</h1>
+<div id="front-matter">
+<div id="motd-area">
+        This is documentation for development version v0.10-dev
+       (<a href="http://forrest.apache.org/pluginDocs/">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#overview">Overview</a>
+</li>
+<li>
+<a href="#What+is+a+Forrest+Plugin%3F">What is a Forrest Plugin?</a>
+<ul class="minitoc">
+<li>
+<a href="#pluginTypes">Types of Plugin</a>
+<ul class="minitoc">
+<li>
+<a href="#inputPlugins">Input Plugins</a>
+</li>
+<li>
+<a href="#outputPlugins">Output Plugins</a>
+</li>
+<li>
+<a href="#internalPlugins">Internal Plugins</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Naming+Conventions">Naming Conventions</a>
+</li>
+<li>
+<a href="#An+Example+Plugin">An Example Plugin</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#What+Does+a+Forrest+Plugin+Look+Like%3F">What Does a Forrest Plugin Look Like?</a>
+<ul class="minitoc">
+<li>
+<a href="#The+IMS+Manifest+Plugin">The IMS Manifest Plugin</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#How+does+Installation+work%3F">How does Installation work?</a>
+</li>
+<li>
+<a href="#Further+Reading">Further Reading</a>
+</li>
+</ul>
+</div>
+</div>
+    
+<a name="overview"></a>
+<h2 class="underlined_10">Overview</h2>
+<div class="section">
+<p>
+        Forrest can be extended with the addition of plugins. This document
+        describes what a plugin is and outlines the plugin infrastructure so
+        that you can start building your own Forrest extensions.
+      </p>
+</div>
+    
+<a name="What+is+a+Forrest+Plugin%3F"></a>
+<h2 class="underlined_10">What is a Forrest Plugin?</h2>
+<div class="section">
+<p>
+        A Forrest plugin is a set of resources and configuration files that
+        extend the functionality of Forrest. They will typically consist of a
+        sitemap, zero or more stylesheets and zero or more schemas.
+      </p>
+<p>
+        The plugins sitemap is mounted by Forrest's sitemap after the project
+        specific sitemap but before the Forrest default matchers. This allows a
+        plugin to override/extend default Forrest behaviour. By adopting a
+        plugin model we can keep the core of Forrest tightly focused on the
+        basic functionality, whilst still facilitating extensions to suit
+        individual projects needs.
+      </p>
+<a name="pluginTypes"></a>
+<h3 class="underlined_5">Types of Plugin</h3>
+<p>
+          There are three types of plugin, <span class="codefrag">input</span>,
+          <span class="codefrag">output</span> and <span class="codefrag">internal</span>. Each plugin has a
+          specific role to play and extends a different part of Forrest:
+        </p>
+<pre class="code">
+                            internal plugins
+                       (site.xml, abs-linkmap etc.)
+                                   |
+                                  \|/
+                                   .
+          input format --&gt; intermediate format --&gt; output format 
+                        .                       .
+                       /|\                     /|\
+                        |                       |
+                   input plugin            output plugin
+                     (**.xml)         (**.html, **.pdf etc.) 
+</pre>
+<a name="inputPlugins"></a>
+<h4>Input Plugins</h4>
+<p>
+            Input plugins provide a new source format. For example, the
+            OpenOffice.org plugin extends Forrest to allow the use of
+            OpenOffice.org Application file formats.
+          </p>
+<p>
+            An input plugin provides an <span class="codefrag">input.xmap</span> file. This
+            provides the source matchers (i.e. **.xml), it is mounted in
+            forrest.xmap before the default forrest **.xml behaviour and
+            therefore can override that default behaviour but it will not
+            interfere with any internal Forrest infrastructure matches, or any
+            other plugins infrastructure matches.
+          </p>
+<p>
+            An input plugin may also provide a <span class="codefrag">resources.xmap</span> file.
+            This can be used to match additional resources that are not stored
+            in XML files, for example, javascript files.
+          </p>
+<a name="outputPlugins"></a>
+<h4>Output Plugins</h4>
+<p>
+            Output plugins provide a new output format. For example, the s5
+            plugin extends Forrest to produce HTML slides from Forrest
+            documents.
+          </p>
+<p>
+            An output plugin provides an <span class="codefrag">output.xmap</span> file. This
+            provides the relevant output matchers (i.e. **.html, **.pdf,
+            **.slides), it is mounted before any of the default matchers for
+            Forrest and so can override this default behaviour.
+          </p>
+<a name="internalPlugins"></a>
+<h4>Internal Plugins</h4>
+<p>
+            Internal plugins are for advanced use only. They provide ways of
+            extending or overriding Forrest's internal operations. For example,
+            the IMSManifest plugin allows Forrest projects to use an IMS
+            Manifest file instead of a site.xml and tabs.xml configuration
+            files.
+          </p>
+<p>
+            Internal plugins provide an <span class="codefrag">internal.xmap</span> file. This
+            provides the infrastructure matchers (i.e. site.xml, faq.xml,
+            issues.xml), and will be mounted before *any* of the Forrest
+            matches. This sitemap can override any behaviour within Forrest and
+            so developers of these plugins must be especially careful with the
+            construction of their matchers, since they will be processed before
+            any other matchers and consequently can easily break existing
+            functionality. You must only do a &lt;map:generate ...&gt; if you
+            are certain you are going to process the full result.
+          </p>
+<a name="Naming+Conventions"></a>
+<h3 class="underlined_5">Naming Conventions</h3>
+<p>
+          Technically you can name a plugin anything you like with one small
+          restriction (see below). However, we do have some naming conventions
+          that we recomend you follow. This is to minimise the chances of
+          collision between plugins from different developers.
+        </p>
+<p>
+          The name should be structured like a java package name, and should
+          include a relevant reverse domain name. For example:
+        </p>
+<pre class="code">org.apache.forrest.plugin.PLUGIN_TYPE.PLUGIN_NAME</pre>
+<pre class="code">net.sf.forrestPlugins.PLUGIN_TYPE.PLUGIN_NAME</pre>
+<p>
+          Where <span class="codefrag">PLUGIN_TYPE</span> is either "internal", "input" or
+          "output" and <span class="codefrag">PLUGIN_NAME"</span> is a suitable name chosen by
+          yourself.
+        </p>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+          Plugin names cannot have a '-' character in them. This character is
+          used to indicate the start of a version number when defining a plugin
+          to be used. See <a href="../../pluginDocs/plugins_0_100/usingPlugins.html">Using Plugins</a> for
+          more information.
+        </div>
+</div>
+<a name="An+Example+Plugin"></a>
+<h3 class="underlined_5">An Example Plugin</h3>
+<p>
+          In order to fully understand the applicability of Forrest Plugins we
+          will consider an extension to the way in which Forrest defines the
+          structure of the site. By default Forrest uses a site.xml file to
+          define navigation through the site and a tabs.xml file to define the
+          tabs across the top of the page. But what if we want to use a
+          different file to describe site structure? For example, what if we
+          want to use an IMS Manifest file from the SCORM content package
+          standards (http://www.adlnet.org/).
+        </p>
+<p>
+          An IMS Manifest file describes the structure of a site. It is also
+          possible to define a set of rules for extracting tab information from
+          such a file. Consequently, it is possible to use an IMSManifest file
+          to create Forrest's site.xml and tabs.xml files. The advantage would
+          be that we can then use SCORM compliant content objects within
+          Forrest.
+        </p>
+<p>
+          Unfortunately, IMS Manifests are much more complex than site.xml and
+          tabs.xml files. Therefore, not all users will want to use them. Adding
+          the functionality as an optional plugin seems to be the ideal
+          solution.
+        </p>
+</div>
+    
+<a name="What+Does+a+Forrest+Plugin+Look+Like%3F"></a>
+<h2 class="underlined_10">What Does a Forrest Plugin Look Like?</h2>
+<div class="section">
+<p>
+        Plugins will need to conform to a specified directory structure. This
+        mirrors the default forrest directory structure:
+      </p>
+<pre class="code">
+[plugin_name]
+  |
+  |-- plugin control files (xmap etc.)
+  |
+  |-- conf
+  |   |
+  |   `-- cocoon and component config files (e.g. *.xconf, jtidy)
+  |
+  |-- resources
+      |
+      |-- schema
+      |   |
+      |   |-- catalog.xcat
+      |   |
+      |   `-- dtd (DTDs etc.)
+      |
+      `-- stylesheets (XSLs etc.)
+</pre>
+<a name="The+IMS+Manifest+Plugin"></a>
+<h3 class="underlined_5">The IMS Manifest Plugin</h3>
+<p>
+          If we consider the IMS Manifest Plugin described above, we see that we
+          will need the following files and directory structure:
+        </p>
+<pre class="code">
+org.apache.forrest.plugin.internal.IMSManifest
+  |
+  |-- sitemap.xmap
+  |
+  |-- resources
+      |
+      |-- stylesheets
+                    |
+                    |- imsmanifest2site.xsl
+                    |- imsmanifest2tabs.xsl
+                    |- pathutils.xsl
+                    |- repositoryUtils.xsl
+</pre>
+<p>
+          The sitemap.xmap file will override the default behaviour for the
+          navigation generation matchers in Forrest, for example, it contains a
+          matcher as follows:
+        </p>
+<pre class="code">
+
+&lt;map:match pattern="abs-menulinks"&gt;
+  &lt;map:select type="exists"&gt;
+    &lt;map:when test="{properties:content.xdocs}imsmanifest.xml"&gt;
+       &lt;map:generate src="{properties:content.xdocs}imsmanifest.xml" /&gt;
+       &lt;map:transform src="resources/stylesheets/imsmanifest2site.xsl"/&gt;
+       &lt;map:transform src="{forrest:forrest.stylesheets}/absolutize-linkmap.xsl" /&gt;
+       &lt;map:transform src="{forrest:forrest.stylesheets}/site2site-normalizetabs.xsl" /&gt;
+     &lt;map:serialize type="xml"/&gt;
+   &lt;/map:when&gt;
+   &lt;map:when test="{properties:content.xdocs}site.xml"&gt;
+      &lt;map:generate src="{properties:content.xdocs}site.xml" /&gt;
+      &lt;map:transform src="{forrest:forrest.stylesheets}/absolutize-linkmap.xsl" /&gt;
+      &lt;map:transform src="{forrest:forrest.stylesheets}/site2site-normalizetabs.xsl" /&gt;
+      &lt;map:transform src="{forrest:forrest.stylesheets}/normalizehrefs.xsl"/&gt;
+    &lt;map:serialize type="xml"/&gt;
+  &lt;/map:when&gt;
+  &lt;/map:select&gt;
+&lt;/map:match&gt;
+
+        </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+          Note that this matcher will default to the behaviour provided by
+          Forrest if there is no imsmanifest.xml file present in the project. At
+          present it is necessary to copy this default behaviour from the
+          original Forrest *.xmap files. We hope to improve on this in the
+          future.
+        </div>
+</div>
+</div>
+    
+<a name="How+does+Installation+work%3F"></a>
+<h2 class="underlined_10">How does Installation work?</h2>
+<div class="section">
+<p>
+        See the <a href="../../pluginDocs/plugins_0_100/usingPlugins.html">Using Plugins</a> for an overview
+        of how the plugin installation system works and the places and order
+        that will be searched.
+      </p>
+<p>
+        When Forrest installs a plugin it downloads a zip of the plugin code and
+        extracts it into the <span class="codefrag">plugins</span> directory of Forrest and an
+        entry is made in a temporary sitemap that manages plugins for your
+        content object. For example, installing the IMSManifest plugin described
+        above will result in the following entry being added to the this
+        temporary sitemap:
+      </p>
+<pre class="code">
+
+&lt;map:select type="exists"&gt;
+  &lt;map:when test="output.xmap"&gt;
+    &lt;map:mount uri-prefix="" 
+      src="sitemap.xmap" 
+      check-reload="yes" 
+      pass-through="true"/&gt;
+  &lt;/map:when&gt;
+&lt;/map:select&gt;
+  
+      </pre>
+<p>
+        To be more accurate, the entries are made in one of three temporary
+        sitemaps, input.xmap, output.xmap and resources.xmap. These temporary
+        sitemaps are rebuilt each time the content object is built or run, thus
+        we are always guarenteed of having the right plugins installed.
+      </p>
+</div>
+    
+<a name="Further+Reading"></a>
+<h2 class="underlined_10">Further Reading</h2>
+<div class="section">
+<p>
+        If you want to build a plugin you might like to start with our
+        <a href="../../docs_0_100/howto/howto-buildPlugin.html">HowTo on Building Plugins</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-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+    Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+    logos are trademarks of The Apache Software Foundation.
+  </div>
+<!--+
+    |end bottomstrip
+    +-->
+</div>
+</body>
+</html>

Propchange: forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/pluginDocs/plugins_0_100/usingPlugins.html
URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_100/usingPlugins.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/pluginDocs/plugins_0_100/usingPlugins.html (added)
+++ forrest/site/pluginDocs/plugins_0_100/usingPlugins.html Tue Feb  8 09:44:46 2011
@@ -0,0 +1,533 @@
+<!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.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Extending Forrest with Plugins (v0.10-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 Software Foundation</a> &gt; <a href="http://forrest.apache.org/">Apache 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>
+<a class="unselected" href="../../versions/index.html">Versioned Docs</a>
+</li>
+<li class="current">
+<a class="selected" 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="../../pluginDocs/plugins_0_90/index.html">0.90 (current)</a><a class="selected" href="../../pluginDocs/plugins_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../../pluginDocs/plugins_0_80/index.html">0.80 (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.100 Plugins</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../pluginDocs/plugins_0_100/index.html">Index</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Using Plugins</div>
+</div>
+<div class="menuitem">
+<a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">Plugin Infrastructure</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+        This is documentation for development version v0.10-dev
+       (<a href="http://forrest.apache.org/pluginDocs/">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://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+<!--+
+    |end Menu
+    +-->
+<!--+
+    |start content
+    +-->
+<div id="content">
+<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>Extending Forrest with Plugins</h1>
+<div id="front-matter">
+<div id="motd-area">
+        This is documentation for development version v0.10-dev
+       (<a href="http://forrest.apache.org/pluginDocs/">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#overview">Overview</a>
+<ul class="minitoc">
+<li>
+<a href="#available">What plugins are available?</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#install">How is a Plugin Installed?</a>
+<ul class="minitoc">
+<li>
+<a href="#required">List of Plugins Needed by the Project</a>
+</li>
+<li>
+<a href="#version">What Version of Plugins will be used ?</a>
+</li>
+<li>
+<a href="#sources">Where does Forrest look for Plugins sources?</a>
+<ul class="minitoc">
+<li>
+<a href="#Overview">Overview</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#local-deploy">Editing plugins sources to enhance functionality</a>
+</li>
+<li>
+<a href="#no-plugins">Upgrading from a Version of Forrest Without Plugins</a>
+</li>
+<li>
+<a href="#conflict">Avoiding Plugin Conflicts</a>
+</li>
+<li>
+<a href="#more">Further Reading</a>
+</li>
+</ul>
+</div>
+</div>
+    
+<a name="overview"></a>
+<h2 class="underlined_10">Overview</h2>
+<div class="section">
+<p>
+        Forrest provides the core functionality for generating documentation in
+        various output formats from a range of input formats. However, it does
+        not end there. Forrest can be extended through the addition of plugins.
+        This document serves as an introduction to the Forrest plugin mechanism.
+      </p>
+<a name="available"></a>
+<h3 class="underlined_5">What plugins are available?</h3>
+<p>
+          You can run the command <span class="codefrag">forrest available-plugins</span> to get
+          a list of the known plugins for Forrest.
+        </p>
+<p>
+          If you would like to have your own plugin added to this list then
+          contact the <a href="../../mail-lists.html">developer mailing list</a>.
+        </p>
+</div>
+    
+<a name="install"></a>
+<h2 class="underlined_10">How is a Plugin Installed?</h2>
+<div class="section">
+<a name="required"></a>
+<h3 class="underlined_5">List of Plugins Needed by the Project</h3>
+<p>
+          If a site requires one or more plugins then the site designer will
+          have to list them in the <span class="codefrag">project.required.plugins</span>
+          property in the projects <span class="codefrag">forrest.properties</span> file. When
+          Forrest builds the site it will automatically discover the plugins and
+          install them. In otherwords, the user needs do nothing.
+        </p>
+<p>
+          For example,
+        </p>
+<pre class="code">
+project.required.plugins=org.apache.forrest.plugin.output.pdf,
+  org.apache.forrest.plugin.input.simplifiedDocbook</pre>
+<p>
+          (note that that is all in one line with no spaces)
+          will cause Forrest to load the plugins called
+          "org.apache.forrest.plugin.output.pdf" and
+          "org.apache.forrest.plugin.input.simplifiedDocbook".
+        </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+          By default a new forrest project has that property configured to
+          include some plugins. Currently there is only one to generate PDF
+          output from your source documents.
+        </div>
+</div>
+<a name="version"></a>
+<h3 class="underlined_5">What Version of Plugins will be used ?</h3>
+<p>
+          In the absence of a version number for the plugin (as is the case in
+          the example above) the most recent version that is applicabe to your
+          release of Forrest will be used. This may result in unexpected
+          behaviour if a new version of the plugin has been released that is
+          incompatible with your current site. To force Forrest into using a
+          specific version of a plugin you should add "-VERSION_NUMBER" to the
+          end of the plugin name. For example, to force forrest to use the version 0.2
+          of the "output.pdf" plugin you would use
+          <span class="codefrag">org.apache.forrest.plugin.output.pdf-0.2</span>. If
+          you define a version of the plugin that does not exist then it will
+          fall back to using the most recent version available. This feature is
+          useful when developing a new site as you can quickly force a plugin
+          upgrade by deleting all installed plugins (use the command 'ant
+          cleanPlugins'). However, this might result in the installation of an
+          in-development plugin, therefore in a production environment you
+          should always specify a known working version.
+        </p>
+<a name="sources"></a>
+<h3 class="underlined_5">Where does Forrest look for Plugins sources?</h3>
+<a name="Overview"></a>
+<h4>Overview</h4>
+<p>
+            This is fairly complex, so here is a simple overview. If you want to
+            know the details you need to read the rest of this section. For most
+            people this overview will be sufficient.
+          </p>
+<p>
+            Forrest will try and retrieve a plugin from local source files
+            first, if that fails it will look on a remote distribution server.
+            Once it finds a copy of the plugin it will deploy it to the local
+            Forrest instance and use it from there.
+          </p>
+<p>
+            The local directories that will be searched are defined in the
+            <span class="codefrag">project.required.plugins.src</span> property, which is defined
+            in the <span class="codefrag">forrest.properties</span> file. By default this is set
+            to
+            <span class="codefrag">${forrest.home}/plugins,${forrest.home}/whiteboard/plugins</span>,
+            which means that these two directories will be searched for plugins.
+          </p>
+<p>
+            If you have a collection of local plugins the directory in which they are located
+            must be added this property. For example, if your local plugins are in <span class="codefrag">/export/forrest_plugins</span>
+            this property should be something like:
+            <span class="codefrag">project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins</span>
+          
+</p>
+<p>
+            You can add this line to your projects
+            <span class="codefrag">forrest.properties</span> file. However, it may be more
+            convenient to add it to a <span class="codefrag">forrest.properties</span> file in
+            your users home directory.
+          </p>
+<p>
+          Forrest uses a fall back mecanism to find the plugins to install for a
+          project.
+        </p>
+<p>
+          For an unversionned plugin, Forrest tries to get it from :
+        </p>
+<ol>
+          
+<li>different local sources directories (<span class="codefrag">project.required.plugins.src</span> property)</li>
+          
+<li>if not found : the remote site in the forrest version directory</li>
+          
+<li>if not found : the remote site (with no forrest version directory)</li>
+        
+</ol>
+<p>
+          For a versionned plugin, Forrest tries to get :
+        </p>
+<ol>
+          
+<li>the versionned plugin from different local sources directories (<span class="codefrag">project.required.plugins.src</span> property)</li>
+          
+<li>if not found : the versionned plugin from the remote site in the forrest version directory</li>
+          
+<li>if not found : the unversionned plugin in different local sources directory (<span class="codefrag">project.required.plugins.src</span> property again)</li>
+          
+<li>if not found : the unversionned plugin from the remote site in the forrest version directory</li>
+          
+<li>if not found : the remote site (with no forrest version directory)</li>
+        
+</ol>
+<p>
+          By default, forrest looks into the two following directories to find
+          plugins sources : <span class="codefrag">${forrest.home}/plugins</span> and
+          <span class="codefrag">${forrest.home}/whiteboard/plugins</span>. It is possible to add
+          other sources locations by specifying the
+          <span class="codefrag">project.required.plugins.src</span> property in the projects
+          <span class="codefrag">forrest.properties</span> file.
+        </p>
+<p>
+          For example,
+        </p>
+<pre class="code">project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins</pre>
+<p>
+          will add the project specific directory
+          <span class="codefrag">${project.home}/plugins</span> to the list of directories to
+          search in.
+        </p>
+<p>
+          If sources are not found, forrest will try to get them from the Web.
+          Forrest <em>knows</em> the plugins description with plugins
+          descriptors files in which plugins are described as follows :
+        </p>
+<pre class="code">
+&lt;plugin name="org.apache.forrest.plugin.output.pdf"
+  type="output"
+  author="Apache Forrest Project"
+  website="http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.output.pdf"
+  url="http://forrest.apache.org/plugins/"
+  version="0.2"&gt;
+  &lt;description&gt;
+    Enable Forrest documents to be output in PDF format.
+  &lt;/description&gt;
+  &lt;forrestVersion&gt;0.8&lt;/forrestVersion&gt;
+&lt;/plugin&gt;
+        </pre>
+<p>
+          The url to download the different plugins is indicated in this file.
+        </p>
+<p>
+          By default, forrest gets the two following plugins descriptors files :
+          <span class="codefrag">http://forrest.apache.org/plugins/plugins.xml</span> and
+          <span class="codefrag">http://forrest.apache.org/plugins/whiteboard-plugins.xml</span>.
+          It is possible to add other plugins descriptors files by specifying
+          the <span class="codefrag">forrest.plugins.descriptors</span> property in the projects
+          <span class="codefrag">forrest.properties</span> file.
+        </p>
+<p>
+          For example,
+        </p>
+<pre class="code">forrest.plugins.descriptors=http://forrest.apache.org/plugins/plugins.xml,http://forrest.apache.org/plugins/whiteboard-plugins.xml,file:///${project.home}/plugins/plugins.xml</pre>
+<p>
+          will add the project specific plugins descriptors file
+          <span class="codefrag">file:///${project.home}/plugins/plugins.xml</span> to the list
+          of descriptors.
+        </p>
+</div>
+    
+<a name="local-deploy"></a>
+<h2 class="underlined_10">Editing plugins sources to enhance functionality</h2>
+<div class="section">
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+        Of course, developers would need the sources. They are available via
+        <a href="../../docs_0_100/howto/../build.html">SVN</a>. Alternatively, see your
+        $FORREST_HOME/build/plugins/ directory. Copy them somewhere for your
+        development and set the project.required.plugins.src property as described
+        above. The SVN method is preferred.
+      </div>
+</div>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+        Until issue
+        <a href="http://issues.apache.org/jira/browse/FOR-388">FOR-388</a> is
+        fixed to enable the use of plugins in-place, any change to sources
+        requires you to either restart forrest or to manually deploy the plugin
+        locally with "ant local-deploy". See Further reading for "How to build a
+        Plugin". It is worth noting that if your changes are to Java files you
+        will always have to restart Forrest to ensure the class loader loads
+        your new classes.
+      </div>
+</div>
+<p>
+        If you need to add specific behaviour to an existing plugin, you should
+        first consider whether your changes will be of use to all users of the
+        plugin or not. If they are of general use then you can edit the plugin
+        source files in their original location (i.e. not in the build
+        directory). Once you have completed your changes please
+        <a href="../../contrib.html#patch">prepare a patch and submit it for
+        inclusion</a> in code base.
+      </p>
+<p>
+        If your changes are specific to your own use of the plugin you can
+        create a local copy of the plugin for this. However, we strongly advise
+        against this since you will need to manually update your plugin each
+        time a new release of the original is made. In the vast majority of
+        cases local enhancements to a plugin wil be of use to the wider
+        communtiy. Please donate back to the project and help keep it vibrant
+        and useful. See the Further Reading section at the end of this document
+        for links to documents with more information.
+      </p>
+</div>
+    
+<a name="no-plugins"></a>
+<h2 class="underlined_10">Upgrading from a Version of Forrest Without Plugins</h2>
+<div class="section">
+<p>
+        The plugin functionality was introduced in version 0.7 of Forrest. At
+        this time some of the functionality previously in Forrest was extracted
+        into a plugin. However, we have not broken backward compatability with
+        earlier versions. In the absence of a
+        <span class="codefrag">project.required.plugins</span> property in the projects
+        <span class="codefrag">forrest.properties</span> file all plugins that contain
+        functionality previously part of Forrest itself will be loaded
+        automatically. Unless you intend to use new functionality provided by a
+        plugin you will not need to make any changes to your project.
+      </p>
+<p>
+        If you do require additional plugin functionality, be sure to include
+        all required plugins in the <span class="codefrag">project.required.plugins</span>
+        property in the project's <span class="codefrag">forrest.properties</span>. You can view
+        <span class="codefrag">main/webapp/default-forrest.properties</span> to see the names of
+        plugins that provide previously core functionality.
+      </p>
+<p>
+        It is also worth noting that there is a small performance improvement if
+        you remove plugins that are not in use. Therefore, if you do not use one
+        or more of the plugins named in the
+        <span class="codefrag">project.required.plugins</span> property of
+        <span class="codefrag">main/webapp/default-forrest.properties</span> it is recomended
+        that you override this value in your project's
+        <span class="codefrag">forrest.properties</span> file.
+      </p>
+</div>
+    
+<a name="conflict"></a>
+<h2 class="underlined_10">Avoiding Plugin Conflicts</h2>
+<div class="section">
+<p>
+        Clashes between plugins can occur. For example, the simplified-docbook
+        and full docbook plugins may try and process the same files. In this
+        instance the one that is mounted first will take precedence. Plugins are
+        mounted in the order they appear in the
+        <span class="codefrag">project.required.plugins</span> property, therefore the mounting
+        order and therefore processing precedence is under user control.
+      </p>
+</div>
+    
+<a name="more"></a>
+<h2 class="underlined_10">Further Reading</h2>
+<div class="section">
+<ul>
+        
+<li>
+<a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">Plugin Infrastructure</a>
+</li>
+        
+<li>
+<a href="../../docs_0_100/howto/howto-buildPlugin.html">How to build a Plugin</a>
+</li>
+      
+</ul>
+</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-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+    Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+    logos are trademarks of The Apache Software Foundation.
+  </div>
+<!--+
+    |end bottomstrip
+    +-->
+</div>
+</body>
+</html>

Propchange: forrest/site/pluginDocs/plugins_0_100/usingPlugins.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/trash/docs_0_50/upgrading_05.html
URL: http://svn.apache.org/viewvc/forrest/site/trash/docs_0_50/upgrading_05.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/trash/docs_0_50/upgrading_05.html (added)
+++ forrest/site/trash/docs_0_50/upgrading_05.html Tue Feb  8 09:44:46 2011
@@ -0,0 +1,530 @@
+<!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.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Upgrading to Forrest 0.5</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 Software Foundation</a> &gt; <a href="http://forrest.apache.org/">Apache 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 class="current">
+<a class="selected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../../contrib.html">Developers</a>
+</li>
+<li>
+<a class="unselected" 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"></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_1.1', '../../skin/')" id="menu_1.1Title" class="menutitle">About</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../index.html" title="Welcome and introduction">About Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../linkmap.html" title="Table of Contents for all Forrest documentation">Documentation ToC</a>
+</div>
+<div class="menuitem">
+<a href="http://forrest.apache.org/mirrors.cgi" title="Download a release from your nearest mirror or get the latest from SVN">Download</a>
+</div>
+<div class="menuitem">
+<a href="../../mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
+</div>
+<div class="menuitem">
+<a href="../../license.html" title="Notes and FAQs about the licensing">License</a>
+</div>
+<div class="menuitem">
+<a href="../../forrest-contract.html" title="What each party can expect">Our contract</a>
+</div>
+<div class="menuitem">
+<a href="../../compliance.html" title="Declare the status of HTML, WAI, CSS compliance">Standards compliance</a>
+</div>
+<div class="menuitem">
+<a href="../../forrest-issues.html" title="List of currently open issues">Open issues</a>
+</div>
+<div class="menuitem">
+<a href="../../who.html" title="Explain who is involved">Who we are</a>
+</div>
+<div class="menuitem">
+<a href="../../flyer.html" title="One-page description">Flyer</a>
+</div>
+<div class="menuitem">
+<a href="../../live-sites.html" title="Some sites created using Apache Forrest technology">Example sites</a>
+</div>
+<div class="menuitem">
+<a href="../../thanks.html" title="Acknowledgment to those who have become involved">Thanks</a>
+</div>
+<div class="menuitem">
+<a href="http://www.apache.org/foundation/sponsorship.html" title="ASF Sponsorship Program">Sponsorship</a>
+</div>
+<div class="menuitem">
+<a href="http://www.apache.org/security/" title="Please report vulnerabilities via ASF Security">Security</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../../skin/')" id="menu_1.2Title" class="menutitle">Related projects</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://www.apache.org/">ASF</a>
+</div>
+<div class="menuitem">
+<a href="http://gump.apache.org/">Apache Gump</a>
+</div>
+<div class="menuitem">
+<a href="http://cocoon.apache.org/">Apache Cocoon</a>
+</div>
+<div class="menuitem">
+<a href="http://lenya.apache.org/">Apache Lenya</a>
+</div>
+<div class="menuitem">
+<a href="http://xml.apache.org/">Apache XML</a>
+</div>
+<div class="menuitem">
+<a href="http://projects.apache.org/">projects.apache.org</a>
+</div>
+</div>
+<div id="credit"></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://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+<!--+
+    |end Menu
+    +-->
+<!--+
+    |start content
+    +-->
+<div id="content">
+<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 Forrest 0.5</h1>
+<div id="front-matter">
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Introduction">Introduction</a>
+</li>
+<li>
+<a href="#New+Features">New Features</a>
+</li>
+<li>
+<a href="#Upgrading+the+sitemap">Upgrading the sitemap</a>
+</li>
+<li>
+<a href="#Version-specific+sitemaps">Version-specific sitemaps</a>
+</li>
+<li>
+<a href="#Excluding+URLs%3A+filterlinks.xsl+removed+and+cli.xconf+added">Excluding URLs: filterlinks.xsl removed and cli.xconf added</a>
+</li>
+<li>
+<a href="#Skin+invocation+changes">Skin invocation changes</a>
+</li>
+<li>
+<a href="#Upgrading+skinconf.xml">Upgrading skinconf.xml</a>
+</li>
+<li>
+<a href="#Upgrading+forrest.properties">Upgrading forrest.properties</a>
+</li>
+<li>
+<a href="#Run+a+clean+target+after+upgrade">Run a clean target after upgrade</a>
+</li>
+<li>
+<a href="#SVGs+should+omit+DOCTYPE+declarations">SVGs should omit DOCTYPE declarations</a>
+</li>
+<li>
+<a href="#To+be+continued...">To be continued...</a>
+</li>
+</ul>
+</div>
+</div>
+    
+<a name="Introduction"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+        This page describes changes to Forrest that affect people who are
+        upgrading from 0.4 and earlier to the 0.5 version. Please post your
+        upgrade experiences to the
+        <a href="../../mail-lists.html#forrest-dev">forrest-dev mailing
+        list</a>. As more experience is gained, this document will be
+        updated.
+      </p>
+</div>
+    
+<a name="New+Features"></a>
+<h2 class="underlined_10">New Features</h2>
+<div class="section">
+<p>
+        This new version includes many changes, as it as been under development
+        for seven months (in part, awaiting the Cocoon 2.1 release). The
+        following list shows some of the key new features for Forrest 0.5 (for
+        the full list of changes, see the
+        <a href="../../docs_0_100/changes.html">change log</a>).
+      </p>
+<ul>
+        
+<li>Significantly faster (100% - 300%) command-line rendering</li>
+        
+<li>Docbook support. The DTDs are shipped. Document types are
+        automatically detected by the sitemap and there is a basic stylesheet
+        which converts DocBook documents to intermediate forrest document-v12
+        for standard rendering. For rendering as full DocBook, see
+        <a href="../../docs_0_100/faq.html#docbook">this FAQ entry</a>.
+       </li>
+        
+<li>Configuration of URLs to ignore with cli.xconf configuration.</li>
+        
+<li>Skin enhancements.</li>
+        
+<li>The document-v12 DTDs are added. You can still use the old
+        document-v11 DTDs if you would rather. However it is easy to upgrade
+        - just change the document type declarations in you project's xdocs
+        and run '<span class="codefrag">forrest validate-xdocs</span>'.</li>
+        
+<li>Automated handling of documents in Wiki syntax. See the
+         fresh-site example which are generated when you
+         '<span class="codefrag">forrest seed</span>' a new project.</li>
+        
+<li>The '<span class="codefrag">forrest backcopy</span>' target copies all
+         types of content that you may have edited under the webapp while
+         doing a '<span class="codefrag">forrest run</span>'.</li>
+        
+<li>Flag for email obfuscation.</li>
+        
+<li>Support for raw un-processed content. See 
+        <a href="../../docs_0_100/faq.html#link_raw">this FAQ entry</a>.
+        </li>
+        
+<li>Element <span class="codefrag">&lt;abstract&gt;</span> is now rendered in the 
+        HTML output.</li>
+        
+<li>Images scale properly in PDF output. See also
+        <a href="../../docs_0_100/faq.html#pdf_images">this FAQ entry</a>.
+        </li>
+        
+<li>Configurable table-of-content depth with new 'toc' element in
+        the <span class="codefrag">skinconf.xml</span> configuration.</li>
+      
+</ul>
+</div>
+    
+<a name="Upgrading+the+sitemap"></a>
+<h2 class="underlined_10">Upgrading the sitemap</h2>
+<div class="section">
+<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 <a href="../../docs_0_100/sitemap-ref.html">Sitemap
+        Reference</a>.
+      </p>
+<p>
+        Users that have overridden and augmented the Forrest 0.4 sitemap.xmap
+        (run '<span class="codefrag">forrest overrides</span>' to see if your project has) will
+        need to:
+      </p>
+<ol>
+        
+<li>Move their overridden sitemap (<span class="codefrag">src/documentation/sitemap.xmap</span>) out the way</li>
+        
+<li>Copy the new sitemap, $FORREST_HOME/context/sitemap.xmap, to <span class="codefrag">src/documentation</span>
+</li>
+        
+<li>Reapply your customizations to the new sitemap.xmap.  Customizations can be determined by comparing your modified
+          sitemap.xmap with 
+          <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/conf/sitemap.xmap?rev=1.66&amp;only_with_tag=FORREST_04">original
+            Forrest 0.4 sitemap</a>.</li>
+      
+</ol>
+</div>
+    
+<a name="Version-specific+sitemaps"></a>
+<h2 class="underlined_10">Version-specific sitemaps</h2>
+<div class="section">
+<p>
+        Forrest 0.5 now supports <em>version-specific sitemaps</em>. Ie., if
+        your project's overridden sitemap is called
+        <span class="codefrag">sitemap-0.5.xmap</span>, then this sitemap will be used in
+        preference to <span class="codefrag">sitemap.xmap</span>, or any other sitemap-*.xmap
+        variants.
+      </p>
+<p>
+        So if, for example, one has:
+      </p>
+<pre class="code">
+        src/documentation/sitemap.xmap
+        src/documentation/sitemap-0.5.xmap
+      </pre>
+<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>
+<pre class="code">
+        src/documentation/sitemap.xmap
+        src/documentation/forrest-0.5.xmap
+      </pre>
+<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>
+<pre class="code">
+        src/documentation/sitemap.xmap
+        src/documentation/sitemap-0.5.xmap
+        src/documentation/sitemap-0.6.xmap
+        src/documentation/sitemap-0.7.xmap
+      </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+        If your <span class="codefrag">forrest.properties</span> defines the
+        <span class="codefrag">forrest.validate.sitemap.{includes,excludes}</span> 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.
+      </div>
+</div>
+</div>
+    
+<a name="Excluding+URLs%3A+filterlinks.xsl+removed+and+cli.xconf+added"></a>
+<h2 class="underlined_10">Excluding URLs: filterlinks.xsl removed and cli.xconf added</h2>
+<div class="section">
+<p>
+        In Forrest 0.4 certain URLs could be excluded from command-line
+        processing by overriding and editing <span class="codefrag">filterlinks.xsl</span> and so
+        excluding the link nodes.
+      </p>
+<p>
+        Forrest 0.5 uses the re-written command-line from Cocoon 2.1.1 which,
+        apart from being much faster, <strong>does not use
+        filterlinks.xsl</strong>. Instead, patterns for command-line inclusion
+        and exclusion can be specified in cli.xconf, as described in
+        <a href="../../docs_0_100/faq.html#cli-xconf">this FAQ entry</a>. There is
+        already a default cli.xconf but you can over-ride that with your own if
+        needed by copying <span class="codefrag">resources/conf/cli.xconf</span> from the Forrest
+        distribution into your project's top-level directory.
+      </p>
+</div>
+    
+<a name="Skin+invocation+changes"></a>
+<h2 class="underlined_10">Skin invocation changes</h2>
+<div class="section">
+<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
+        <span class="codefrag">sitemap.xmap</span> for occurrences of
+        <span class="codefrag">{forrest:forrest.skin}</span>, 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>
+</div>
+    
+<a name="Upgrading+skinconf.xml"></a>
+<h2 class="underlined_10">Upgrading skinconf.xml</h2>
+<div class="section">
+<p>
+        Look at the
+        <a href="http://cvs.apache.org/viewcvs/xml-forrest/src/resources/fresh-site/src/documentation/skinconf.xml.diff?r1=1.7%3AFORREST_04&amp;r2=1.15%3AFORREST_05&amp;diff_format=h">differences
+        for the sample skinconf.xml</a> as a guide. You will need to update
+        the internal DTD and add several new elements.
+      </p>
+</div>
+    
+<a name="Upgrading+forrest.properties"></a>
+<h2 class="underlined_10">Upgrading forrest.properties</h2>
+<div class="section">
+<p>
+        Look at the
+        <a href="http://cvs.apache.org/viewcvs/xml-forrest/src/resources/fresh-site/forrest.properties.diff?r1=1.20%3AFORREST_04&amp;r2=1.32%3AFORREST_05&amp;diff_format=h">differences
+        for the sample forrest.properties</a> as a guide. Note that
+        project.sitemap has changed to project.sitemap-dir and note that
+        cli.xconf now controls some settings that were previously controlled by
+        forrest.properties, such as project.start-uri
+      </p>
+</div>
+    
+<a name="Run+a+clean+target+after+upgrade"></a>
+<h2 class="underlined_10">Run a clean target after upgrade</h2>
+<div class="section">
+<p>
+        To avoid any issue with old classes being loaded, run a '<span class="codefrag">forrest
+        clean</span>' just after you upgraded to this version.
+      </p>
+</div>
+    
+<a name="SVGs+should+omit+DOCTYPE+declarations"></a>
+<h2 class="underlined_10">SVGs should omit DOCTYPE declarations</h2>
+<div class="section">
+<div class="fixme">
+<div class="label">Fixme (forrest-dev)</div>
+<div class="content">
+        Is this note still relevant?
+      </div>
+</div>
+<p>
+        In Forrest 0.5, sites that render SVGs may encounter
+        ClassCastExceptions:
+      </p>
+<pre class="code">
+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)
+...</pre>
+<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
+        <span class="codefrag">src/documentation/resources/images/*.svg</span> files, and comment
+        out the <strong>&lt;!DOCTYPE ... &gt;</strong> declaration.
+      </p>
+</div>
+    
+<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>
+  
+<span class="version">
+          version 1.8</span>
+</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-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+    Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+    logos are trademarks of The Apache Software Foundation.
+  </div>
+<!--+
+    |end bottomstrip
+    +-->
+</div>
+</body>
+</html>

Propchange: forrest/site/trash/docs_0_50/upgrading_05.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/trash/docs_0_70/upgrading_07.html
URL: http://svn.apache.org/viewvc/forrest/site/trash/docs_0_70/upgrading_07.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/trash/docs_0_70/upgrading_07.html (added)
+++ forrest/site/trash/docs_0_70/upgrading_07.html Tue Feb  8 09:44:46 2011
@@ -0,0 +1,439 @@
+<!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.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Upgrading to Apache Forrest 0.7</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 Software Foundation</a> &gt; <a href="http://forrest.apache.org/">Apache 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 class="current">
+<a class="selected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../../contrib.html">Developers</a>
+</li>
+<li>
+<a class="unselected" 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"></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_1.1', '../../skin/')" id="menu_1.1Title" class="menutitle">About</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../index.html" title="Welcome and introduction">About Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../linkmap.html" title="Table of Contents for all Forrest documentation">Documentation ToC</a>
+</div>
+<div class="menuitem">
+<a href="http://forrest.apache.org/mirrors.cgi" title="Download a release from your nearest mirror or get the latest from SVN">Download</a>
+</div>
+<div class="menuitem">
+<a href="../../mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
+</div>
+<div class="menuitem">
+<a href="../../license.html" title="Notes and FAQs about the licensing">License</a>
+</div>
+<div class="menuitem">
+<a href="../../forrest-contract.html" title="What each party can expect">Our contract</a>
+</div>
+<div class="menuitem">
+<a href="../../compliance.html" title="Declare the status of HTML, WAI, CSS compliance">Standards compliance</a>
+</div>
+<div class="menuitem">
+<a href="../../forrest-issues.html" title="List of currently open issues">Open issues</a>
+</div>
+<div class="menuitem">
+<a href="../../who.html" title="Explain who is involved">Who we are</a>
+</div>
+<div class="menuitem">
+<a href="../../flyer.html" title="One-page description">Flyer</a>
+</div>
+<div class="menuitem">
+<a href="../../live-sites.html" title="Some sites created using Apache Forrest technology">Example sites</a>
+</div>
+<div class="menuitem">
+<a href="../../thanks.html" title="Acknowledgment to those who have become involved">Thanks</a>
+</div>
+<div class="menuitem">
+<a href="http://www.apache.org/foundation/sponsorship.html" title="ASF Sponsorship Program">Sponsorship</a>
+</div>
+<div class="menuitem">
+<a href="http://www.apache.org/security/" title="Please report vulnerabilities via ASF Security">Security</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../../skin/')" id="menu_1.2Title" class="menutitle">Related projects</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://www.apache.org/">ASF</a>
+</div>
+<div class="menuitem">
+<a href="http://gump.apache.org/">Apache Gump</a>
+</div>
+<div class="menuitem">
+<a href="http://cocoon.apache.org/">Apache Cocoon</a>
+</div>
+<div class="menuitem">
+<a href="http://lenya.apache.org/">Apache Lenya</a>
+</div>
+<div class="menuitem">
+<a href="http://xml.apache.org/">Apache XML</a>
+</div>
+<div class="menuitem">
+<a href="http://projects.apache.org/">projects.apache.org</a>
+</div>
+</div>
+<div id="credit"></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://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+<!--+
+    |end Menu
+    +-->
+<!--+
+    |start content
+    +-->
+<div id="content">
+<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.7</h1>
+<div id="front-matter">
+<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="#clean">Run a clean target after upgrade</a>
+</li>
+<li>
+<a href="#home">New location of $FORREST_HOME</a>
+</li>
+<li>
+<a href="#jdk14">Java 1.4 (or newer) is required</a>
+</li>
+<li>
+<a href="#tips">General upgrade tips</a>
+</li>
+<li>
+<a href="#plugin">Plugin architecture</a>
+</li>
+<li>
+<a href="#configure-plugin">Configure plugins</a>
+</li>
+<li>
+<a href="#raw">Including raw un-processed content</a>
+</li>
+<li>
+<a href="#To+be+continued...">To be continued...</a>
+</li>
+</ul>
+</div>
+</div>
+    
+<a name="introduction"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+        This page describes some changes to Apache Forrest that affect people
+        who are upgrading to the 0.7 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.6 then you will need to
+        see the notes for the previous upgrade.)
+      </p>
+</div>
+    
+<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 <a href="../../docs_0_100/changes.html">change log</a>).
+      </p>
+<ul>
+        
+<li>Plugin architecture</li>
+        
+<li>Java 1.4</li>
+      
+</ul>
+<p>
+        As usual, do a "forrest seed site" in a new directory and compare the
+        forrest.properties and skinconf.xml with that of your project.
+      </p>
+</div>
+    
+<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="home"></a>
+<h2 class="underlined_10">New location of $FORREST_HOME</h2>
+<div class="section">
+<p>
+        $FORREST_HOME is now the top-level of the distribution. Also make sure
+        $PATH gets updated to use the new $FORREST_HOME/bin
+      </p>
+</div>
+    
+<a name="jdk14"></a>
+<h2 class="underlined_10">Java 1.4 (or newer) is required</h2>
+<div class="section">
+<p>
+        Java 1.4 (or newer) is required, starting with this Forrest 0.7 version.
+        For further information, see
+        <a href="../../docs_0_100/faq.html#requirements">FAQ</a>.
+      </p>
+</div>
+    
+<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="plugin"></a>
+<h2 class="underlined_10">Plugin architecture</h2>
+<div class="section">
+<p>
+        See <a href="../../pluginDocs/plugins_0_100/pluginInfrastructure.html">Plugin Infrastructure</a> and
+        <a href="../../pluginDocs/plugins_0_100/usingPlugins.html">Extending Forrest with Plugins</a> and for
+        developing new plugins see <a href="../../docs_0_100/howto/howto-buildPlugin.html">How
+        to Build a Plugin</a>. See the list of
+        <a href="../../pluginDocs/plugins_0_100/index.html">current plugins</a> and their
+        documentation.
+      </p>
+<p>
+        Note that other experimental plugins can be found in the
+        "whiteboard/plugins" directory.
+      </p>
+</div>
+    
+<a name="configure-plugin"></a>
+<h2 class="underlined_10">Configure plugins</h2>
+<div class="section">
+<p>
+        Some functionality has been moved out of the forrest core and into
+        plugins. You will need to declare any plugins that are used by your
+        project, e.g. if you use projectInfo (status, changes, todo) and PDF
+        output, then declare the following in forrest.properties
+      </p>
+<pre class="code">
+project.required.plugins=org.apache.forrest.plugin.input.projectInfo,org.apache.forrest.plugin.output.pdf
+      </pre>
+</div>
+    
+<a name="raw"></a>
+<h2 class="underlined_10">Including raw un-processed content</h2>
+<div class="section">
+<p>
+        The method for including "raw un-processed content" has changed.
+      </p>
+<p>
+        In 0.6 version, the raw content was placed in the
+        src/documentation/content/ directory and potential sub-directories. In
+        the generated site, these links would automatically function. Any linked
+        file with .html extension was not processed and not adorned with Forrest
+        skin and navigation menus.
+      </p>
+<p>
+        It was also possible to place HTML content in the xdocs directory where
+        it would be copied across if it was linked from the main content.
+      </p>
+<p>
+        In 0.7 version, any file that is linked to, needs to be placed in the
+        content/xdocs/ directory structure. Any linked file with .html extension
+        is now processed and is adorned with Forrest skin and navigation menus.
+      </p>
+<p>
+        If you you wish to emulate the behaviour of 0.6 and earlier then you
+        must add the following to your project sitemap.
+      </p>
+<pre class="code">
+&lt;map:match pattern="**.html"&gt;
+ &lt;map:select type="exists"&gt;
+  &lt;map:when test="{properties:content}{0}"&gt;
+    &lt;map:read src="{properties:content}/{0}" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{properties:content}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+  &lt;map:when test="{properties:content.xdocs}{0}"&gt;
+    &lt;map:read src="{properties:content.xdocs}/{0}" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{properties:content.xdocs}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+ &lt;/map:select&gt;
+&lt;/map:match&gt;
+        </pre>
+<p>
+        If you need to include files that are not linked to, then place them in
+        the src/documentation/content/ directories as with the 0.6 version.
+      </p>
+</div>
+    
+<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-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+    Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+    logos are trademarks of The Apache Software Foundation.
+  </div>
+<!--+
+    |end bottomstrip
+    +-->
+</div>
+</body>
+</html>

Propchange: forrest/site/trash/docs_0_70/upgrading_07.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message