<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2005 The Apache Software Foundation or its licensors,
  as applicable.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">

<document>
  <header>
    <title>Extending Forrest with Plugins</title>
  </header>

  <body>
    <section id="overview">
      <title>Overview</title>
      <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>
  
      <section>
        <title>What plugins are available?</title>
        <p>You can run the command <code>forrest available-plugins</code> 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="site:mail-lists">developer mailing list</a>.</p>
      </section>
    </section>
        
    <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>Upgrading from a Version of Forrest Without Plugins</title>
        <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
        <code>project.required.plugins</code> property in the projects 
        <code>forrest.properties</code> 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 top your project.</p>
        
        <p>If you do require additional plugin functionality, be sure to
        include all required plugins in the 
        <code>project.required.plugins</code> property in the project's
        <code>forrest.properties</code>. You can view
        <code>main/webapp/default-forrest.properties</code>
        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 
        <code>project.required.plugins</code> property of 
        <code>main/webapp/default-forrest.properties</code>
        it is recomended that you override this value in your project's
        <code>forrest.properties</code> file.</p>
      </section>
    </section>
    
    <section>
      <title>Avoiding Plugin Conflicts</title>
      <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 
      <code>project.required.plugins</code> property, therefore the mounting 
      order and therefore processing precedence is under user control.</p>
    </section>
    
    <section>
      <title>Further Reading</title>
      <ul>
        <li><a href="site:plugins/infrastructure">Plugin Infrastructure</a></li>
        <li><a href="site:v0.70//howto/buildPlugin">How to build a Plugin</a></li>
      </ul>
    </section>
  </body>
</document>
