Return-Path: 
 <svn-return-5244-apmail-forrest-svn-archive=forrest.apache.org@forrest.apache.org>
Delivered-To: apmail-forrest-svn-archive@www.apache.org
Received: (qmail 96373 invoked from network); 31 Mar 2006 09:20:22 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 31 Mar 2006 09:20:22 -0000
Received: (qmail 43055 invoked by uid 500); 31 Mar 2006 09:20:15 -0000
Delivered-To: apmail-forrest-svn-archive@forrest.apache.org
Received: (qmail 43018 invoked by uid 500); 31 Mar 2006 09:20:14 -0000
Mailing-List: contact svn-help@forrest.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:svn-help@forrest.apache.org>
list-unsubscribe: <mailto:svn-unsubscribe@forrest.apache.org>
List-Post: <mailto:svn@forrest.apache.org>
Reply-To: "Forrest Developers List" <dev@forrest.apache.org>
List-Id: <svn.forrest.apache.org>
Delivered-To: mailing list svn@forrest.apache.org
Received: (qmail 43007 invoked by uid 99); 31 Mar 2006 09:20:14 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 31 Mar 2006 01:20:14 -0800
X-ASF-Spam-Status: No, hits=-9.4 required=10.0
	tests=ALL_TRUSTED,NO_REAL_NAME
X-Spam-Check-By: apache.org
Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194)
    by apache.org (qpsmtpd/0.29) with SMTP; Fri, 31 Mar 2006 01:20:13 -0800
Received: (qmail 95950 invoked by uid 65534); 31 Mar 2006 09:19:09 -0000
Message-ID: <20060331091909.95949.qmail@minotaur.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r390377 -
 /forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
Date: Fri, 31 Mar 2006 09:19:08 -0000
To: svn@forrest.apache.org
From: cdupoirieux@apache.org
X-Mailer: svnmailer-1.0.7
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Author: cdupoirieux
Date: Fri Mar 31 01:19:04 2006
New Revision: 390377

URL: http://svn.apache.org/viewcvs?rev=390377&view=rev
Log:
(FOR-388) A little bit of explanations on what I made ages to understand ;)

Modified:
    forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml

Modified: forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml?rev=390377&r1=390376&r2=390377&view=diff
==============================================================================
--- forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml (original)
+++ forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml Fri Mar 31 01:19:04 2006
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
-  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  Copyright 2002-2006 The Apache Software Foundation or its licensors,
   as applicable.
 
   Licensed under the Apache License, Version 2.0 (the "License");
@@ -43,33 +43,63 @@
         
     <section>
       <title>How is a Plugin Installed?</title>
-  
-      <p>If a site requires one or more plugins then the site designer will 
-      have named them in the <code>project.required.plugins</code> property 
-      in the projects <code>forrest.properties</code> file. When Forrest 
-      builds the site it will automatically discover the plugin and install 
-      it. In otherwords, the user need do nothing. For example, 
-      <code>project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook</code>
-      will cause Forrest to load the plugins called "org.apache.forrest.plugin.input.OpenOffice.org" and
-      "org.apache.forrest.plugin.input.simplifiedDocbook".</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.input.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>
-  
+        <section>
+          <title>List of Plugins Needed by the Project</title>
+          <p>If a site requires one or more plugins then the site designer will 
+           have to list them in the <code>project.required.plugins</code> property 
+           in the projects <code>forrest.properties</code> 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, 
+           <source>project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook</source>
+           will cause Forrest to load the plugins called "org.apache.forrest.plugin.input.OpenOffice.org" and
+           "org.apache.forrest.plugin.input.simplifiedDocbook".</p>
+           <note>By default a new forrest project includes plugins to generate 
+           PDF output from your source documents.</note>
+        </section>
+        <section>
+          <title>What Version of Plugins will be used ?</title>
+          <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
+          <code>org.apache.forrest.plugin.input.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>
+        </section>
+        <section>
+          <title>Where does Forrest Look for Plugins sources ?</title>
+          <p>By default, forrest looks into the two following directories to find plugins sources : <code>${forrest.home}/plugins</code> and <code>${forrest.home}/whiteboard/plugins</code>.
+          It is possible to add other sources locations by specifying the <code>project.required.plugins.src</code> property 
+          in the projects <code>forrest.properties</code> file.</p>
+          <p>For example, <source>project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,${project.home}/plugins</source>
+           will add the project specific directory <code>${project.home}/plugins</code> 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>
+          <source><![CDATA[<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>]]></source>
+          <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 : <code>http://forrest.apache.org/plugins/plugins.xml</code> and <code>http://forrest.apache.org/plugins/whiteboard-plugins.xml</code>.
+          It is possible to add other plugins descriptors files by specifying the <code>forrest.plugins.descriptors</code> property 
+          in the projects <code>forrest.properties</code> file.</p>
+          <p>For example, <source>forrest.plugins.descriptors=http://forrest.apache.org/plugins/plugins.xml,http://forrest.apache.org/plugins/whiteboard-plugins.xml,file:///${project.home}/plugins/plugins.xml</source>
+          will add the project specific plugins descriptors file <code>file:///${project.home}/plugins/plugins.xml</code> to the list of descriptors.</p>
+        </section>
       <section>
         <title>Upgrading from a Version of Forrest Without Plugins</title>
         <p>The plugin functionality was introduced in version 0.7 of Forrest.