forrest-site-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r529910 [22/22] - in /forrest/site: docs_0_90/ docs_0_90/howto/ docs_0_90/howto/cvs-ssh/ docs_0_90/howto/multi/ docs_0_90/images/ pluginDocs/plugins_0_90/
Date Wed, 18 Apr 2007 08:11:05 GMT
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> &gt; <a href="http://forrest.apache.org/">forrest</a><script
src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<!--+
+    |header
+    +-->
+<div class="header">
+<!--+
+    |start group logo
+    +-->
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../images/apache-forrest.png"
title="The Apache Software Foundation"></a>
+</div>
+<!--+
+    |end group logo
+    +-->
+<!--+
+    |start Project Logo
+    +-->
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif"
title="Apache Forrest"></a>
+</div>
+<!--+
+    |end Project Logo
+    +-->
+<!--+
+    |start Search
+    +-->
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank
(this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search
the site with google">&nbsp; 
+                    <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+    |end search
+    +-->
+<!--+
+    |start Tabs
+    +-->
+<ul id="tabs">
+<li>
+<a class="unselected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../../contrib.html">Developers</a>
+</li>
+<li>
+<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">
+
+             &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.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: 
+	          &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="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">
+&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="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">&nbsp;</div>
+</div>
+<div id="footer">
+<!--+
+    |start bottomstrip
+    +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+//  --></script>
+</div>
+<div class="copyright">
+        Copyright &copy;
+         2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+<!--+
+    |end bottomstrip
+    +-->
+</div>
+</body>
+</html>

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



Mime
View raw message