Added: forrest/site/pluginDocs/plugins_0_90/usingPlugins.html
URL:
http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_90/usingPlugins.html?view=auto&rev=529910
==============================================================================
--- forrest/site/pluginDocs/plugins_0_90/usingPlugins.html (added)
+++ forrest/site/pluginDocs/plugins_0_90/usingPlugins.html Wed Apr 18 01:10:58
2007
@@ -0,0 +1,519 @@
+<!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.9-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Extending Forrest with Plugins (v0.9-dev)</title>
+<link type="text/css" href="../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../skin/screen.css"
rel="stylesheet">
+<link media="print" type="text/css" href="../../skin/print.css"
rel="stylesheet">
+<link type="text/css" href="../../skin/profile.css" rel="stylesheet">
+<script src="../../skin/getBlank.js" language="javascript"
type="text/javascript"></script><script src="../../skin/getMenu.js"
language="javascript" type="text/javascript"></script><script
src="../../skin/fontsize.js" language="javascript"
type="text/javascript"></script>
+<link rel="shortcut icon" href="../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/";>apache</a> > <a
href="http://forrest.apache.org/";>forrest</a><script
src="../../skin/breadcrumbs.js" language="JavaScript"
type="text/javascript"></script>
+</div>
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://www.apache.org/";><img class="logoImage" alt="Apache"
src="../../images/apache-forrest.png" title="The Apache Software
Foundation"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogo">
+<a href="http://forrest.apache.org/";><img class="logoImage" alt="Forrest"
src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<form action="http://www.google.com/search"; method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input
onFocus="getBlank (this, 'Search the site with google');" size="25" name="q"
id="query" type="text" value="Search the site with google">
+ <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_80/index.html">0.80
(current)</a><a class="selected"
href="../../pluginDocs/plugins_0_90/index.html">0.90-dev (under
development)</a><a class="unselected"
href="../../pluginDocs/plugins_0_70/index.html">0.70 (past)</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </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.90 Plugins</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display:
block;">
+<div class="menuitem">
+<a href="../../pluginDocs/plugins_0_90/index.html">Index</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Using Plugins</div>
+</div>
+<div class="menuitem">
+<a href="../../pluginDocs/plugins_0_90/pluginInfrastructure.html">Plugin
Infrastructure</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.9-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://apachecon.com/2007/EU/";><img border="0" title="ApacheCon
Europe 2007" alt="ApacheCon Europe 2007 - logo"
src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png"; style="width:
125px;height: 125px;"></a><a
href="http://people.apache.org/calendar.html#200711";><img border="0"
title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo"
src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png"; style="width:
125px;height: 125px;"></a>
+</div>
+</div>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="usingPlugins.pdf"><img alt="PDF -icon"
src="../../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<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="motd-area">
+ This is documentation for development version v0.9-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>
+
+<a name="N1000D"></a><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="N10016"></a><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="N1002B"></a><a name="install"></a>
+<h2 class="underlined_10">How is a Plugin Installed?</h2>
+<div class="section">
+<a name="N10031"></a><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.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook</pre>
+<p>
+ will cause Forrest to load the plugins called
+ "org.apache.forrest.plugin.input.OpenOffice.org" 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="N1004E"></a><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 1.0
+ version of the OpenOffice.org plugin you would use
+ <span
class="codefrag">org.apache.forrest.plugin.input.OpenOffice.org-1.0</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="N1005B"></a><a name="sources"></a>
+<h3 class="underlined_5">Where does Forrest look for Plugins sources?</h3>
+<a name="N10061"></a><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 you would like Forrest to
+ use then you need to add the directory to this property. For
+ example:
+ <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="N10100"></a><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">
+ 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="N10118"></a><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="N10140"></a><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="N1014D"></a><a name="more"></a>
+<h2 class="underlined_10">Further Reading</h2>
+<div class="section">
+<ul>
+
+<li>
+<a href="../../pluginDocs/plugins_0_90/pluginInfrastructure.html">Plugin
Infrastructure</a>
+</li>
+
+<li>
+<a href="../../docs_0_90/howto/howto-buildPlugin.html">How to build a
Plugin</a>
+</li>
+
+</ul>
+</div>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </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 ©
+ 2002-2007 <a href="http://www.apache.org/licenses/";>The Apache
Software Foundation.</a>
+</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/pluginDocs/plugins_0_90/usingPlugins.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/pluginDocs/plugins_0_90/usingPlugins.pdf
URL:
http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_90/usingPlugins.pdf?view=auto&rev=529910
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/pluginDocs/plugins_0_90/usingPlugins.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
![http://apache.org/ads/ApacheCon/2007-europe-125x125.png"](http://apache.org/ads/ApacheCon/2007-europe-125x125.png"){kind=link}
![http://apache.org/ads/ApacheCon/2007-usa-125x125.png"](http://apache.org/ads/ApacheCon/2007-usa-125x125.png"){kind=link}