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.
