svn commit: r189861 - in /forrest/trunk/site-author/content/xdocs/docs/plugins: pluginInfrastructure.xml usingPlugins.xml

[rg...@apache.org]

Author: rgardler
Date: Thu Jun  9 17:03:37 2005
New Revision: 189861

URL: http://svn.apache.org/viewcvs?rev=189861&view=rev
Log:
Add basic docs for the new verioned plugin system

Modified:
    forrest/trunk/site-author/content/xdocs/docs/plugins/pluginInfrastructure.xml
    forrest/trunk/site-author/content/xdocs/docs/plugins/usingPlugins.xml

Modified: forrest/trunk/site-author/content/xdocs/docs/plugins/pluginInfrastructure.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs/plugins/pluginInfrastructure.xml?rev=189861&r1=189860&r2=189861&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs/plugins/pluginInfrastructure.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs/plugins/pluginInfrastructure.xml Thu Jun  9 17:03:37 2005
@@ -28,12 +28,6 @@
       <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>
-    
-      <warning>The Plugin Infrastructure is still at an early stage of design 
-      and implementation, consequently this document <em>may</em> be out of date.
-      If you are having problems with any of the details, please search for help
-      on the developer mailing list. If you can't find your answer ask
-      for help on that list.</warning>
     </section>
       
     <section>
@@ -124,7 +118,8 @@
       
       <section>
         <title>Naming Conventions</title>
-        <p>Technically you can name a plugin anything you like. However, we
+        <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>
@@ -138,6 +133,11 @@
         <p>Where <code>PLUGIN_TYPE</code> is either "internal", "input" or
         "output" and <code>PLUGIN_NAME"</code> is a suitable name chosen by
         yourself.</p>
+        
+        <warning>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="site:documentation/plugins/using">Using Plugins</a> for more 
+        information.</warning>
         
       </section>
       

Modified: forrest/trunk/site-author/content/xdocs/docs/plugins/usingPlugins.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs/plugins/usingPlugins.xml?rev=189861&r1=189860&r2=189861&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs/plugins/usingPlugins.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs/plugins/usingPlugins.xml Thu Jun  9 17:03:37 2005
@@ -53,6 +53,20 @@
       will cause Forrest to load the plugins called "org.apache.forrest.plugin.OpenOffice.org" and
       "simplified-docbook".</p>
       
+      <p>In the absence of a version number for the plugin (as is the case in the examples 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 shuld 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
+      <code>org.apache.forrest.plugin.OpenOffice.org-1.0</code> If you define a version of the
+      plugin that does not exist then it will fall back to using the most recent version avialable.
+      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>
+      
       <p>By default a new forrest project includes plugins to generate 
       PDF output from your source documents.</p>