Mailing List Archive: 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

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">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<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>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<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"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<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>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<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>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<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>
+
+<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>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <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 --> intermediate format --> 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 <map:generate ...> 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">
+
+<map:match pattern="abs-menulinks">
+ <map:select type="exists">
+ <map:when test="{properties:content.xdocs}imsmanifest.xml">
+ <map:generate src="{properties:content.xdocs}imsmanifest.xml" />
+ <map:transform src="resources/stylesheets/imsmanifest2site.xsl"/>
+ <map:transform src="{forrest:forrest.stylesheets}/absolutize-linkmap.xsl" />
+ <map:transform src="{forrest:forrest.stylesheets}/site2site-normalizetabs.xsl" />
+ <map:serialize type="xml"/>
+ </map:when>
+ <map:when test="{properties:content.xdocs}site.xml">
+ <map:generate src="{properties:content.xdocs}site.xml" />
+ <map:transform src="{forrest:forrest.stylesheets}/absolutize-linkmap.xsl" />
+ <map:transform src="{forrest:forrest.stylesheets}/site2site-normalizetabs.xsl" />
+ <map:transform src="{forrest:forrest.stylesheets}/normalizehrefs.xsl"/>
+ <map:serialize type="xml"/>
+ </map:when>
+ </map:select>
+</map:match>
+
+ </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">
+
+<map:select type="exists">
+ <map:when test="output.xmap">
+ <map:mount uri-prefix=""
+ src="sitemap.xmap"
+ check-reload="yes"
+ pass-through="true"/>
+ </map:when>
+</map:select>
+
+ </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>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 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>
+
+</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">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<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>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<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"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<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>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<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>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<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>
+
+<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>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <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">
+<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">
+ <description>
+ Enable Forrest documents to be output in PDF format.
+ </description>
+ <forrestVersion>0.8</forrestVersion>
+</plugin>
+ </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>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 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>
+
+</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">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<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>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<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"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<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>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs"></div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<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>
+
+<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>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <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"><abstract></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&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&r2=1.15%3AFORREST_05&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&r2=1.32%3AFORREST_05&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><!DOCTYPE ... ></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>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 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>
+
+</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">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<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>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<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"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<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>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs"></div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<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>
+
+<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>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <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">
+<map:match pattern="**.html">
+ <map:select type="exists">
+ <map:when test="{properties:content}{0}">
+ <map:read src="{properties:content}/{0}" mime-type="text/html"/>
+ 
+ </map:when>
+ <map:when test="{properties:content.xdocs}{0}">
+ <map:read src="{properties:content.xdocs}/{0}" mime-type="text/html"/>
+ 
+ </map:when>
+ </map:select>
+</map:match>
+ </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>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 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>
+
+</div>
+</body>
+</html>

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