forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r527010 [22/26] - in /forrest/trunk/site-author/content: ./ skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/ xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/ xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_...
Date Tue, 10 Apr 2007 03:48:57 GMT
Modified: forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml (original)
+++ forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml Mon Apr  9 20:48:52 2007
@@ -16,41 +16,42 @@
   limitations under the License.
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
-
 <document>
   <header>
     <title>Plugin Infrastructure</title>
   </header>
-
   <body>
     <section id="overview">
       <title>Overview</title>
-      <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>
+      <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>
     </section>
-      
     <section>
       <title>What is a Forrest Plugin?</title>
-
-      <p>A Forrest plugin is a set of resources and configuration files that 
-      extend the functionality of Forrest. They will typically consist of a 
-      sitemap, zero or more stylesheets and zero or more schemas.</p>
-
-      <p>The plugins sitemap is mounted by Forrest's sitemap after the project 
-      specific sitemap but before the Forrest default matchers. This allows 
-      a plugin to override/extend default Forrest behaviour. By adopting a 
-      plugin model we can keep the core of Forrest tightly 
-      focused on the basic functionality, whilst still facilitating extensions 
-      to suit individual projects needs.</p>
-      
+      <p>
+        A Forrest plugin is a set of resources and configuration files that
+        extend the functionality of Forrest. They will typically consist of a
+        sitemap, zero or more stylesheets and zero or more schemas.
+      </p>
+      <p>
+        The plugins sitemap is mounted by Forrest's sitemap after the project
+        specific sitemap but before the Forrest default matchers. This allows a
+        plugin to override/extend default Forrest behaviour. By adopting a
+        plugin model we can keep the core of Forrest tightly focused on the
+        basic functionality, whilst still facilitating extensions to suit
+        individual projects needs.
+      </p>
       <section id="pluginTypes">
         <title>Types of Plugin</title>
-        <p>There are three types of plugin, <code>input</code>,
-        <code>output</code> and <code>internal</code>. Each plugin has a 
-        specific role to play and extends a different part of Forrest:</p>
-        
-<source>
+        <p>
+          There are three types of plugin, <code>input</code>,
+          <code>output</code> and <code>internal</code>. Each plugin has a
+          specific role to play and extends a different part of Forrest:
+        </p>
+        <source>
                             internal plugins
                        (site.xml, abs-linkmap etc.)
                                    |
@@ -63,116 +64,124 @@
                    input plugin            output plugin
                      (**.xml)         (**.html, **.pdf etc.) 
 </source>
-        
         <section id="inputPlugins">
           <title>Input Plugins</title>
-          <p>Input plugins provide a new source format. For example, the
-          OpenOffice.org plugin extends Forrest to allow the use of
-          OpenOffice.org Application file formats.</p>
-          
-          <p>An input plugin provides an <code>input.xmap</code> file. 
-          This provides the source matchers (i.e. **.xml), it is 
-          mounted in forrest.xmap before the default forrest **.xml behaviour 
-          and therefore can override that default behaviour but it will not 
-          interfere with any internal Forrest infrastructure matches, or any 
-          other plugins infrastructure matches.</p>
-          
-          <p>An input plugin may also provide a <code>resources.xmap</code>
-          file. This can be used to match additional resources that are not 
-          stored in XML files, for example, javascript files.</p>
+          <p>
+            Input plugins provide a new source format. For example, the
+            OpenOffice.org plugin extends Forrest to allow the use of
+            OpenOffice.org Application file formats.
+          </p>
+          <p>
+            An input plugin provides an <code>input.xmap</code> file. This
+            provides the source matchers (i.e. **.xml), it is mounted in
+            forrest.xmap before the default forrest **.xml behaviour and
+            therefore can override that default behaviour but it will not
+            interfere with any internal Forrest infrastructure matches, or any
+            other plugins infrastructure matches.
+          </p>
+          <p>
+            An input plugin may also provide a <code>resources.xmap</code> file.
+            This can be used to match additional resources that are not stored
+            in XML files, for example, javascript files.
+          </p>
         </section>
-        
         <section id="outputPlugins">
           <title>Output Plugins</title>
-          
-          <p>Output plugins provide a new output format. For example, the
-          s5 plugin extends Forrest to produce HTML slides from Forrest
-          documents.</p>
-          
-          <p>An output plugin provides an <code>output.xmap</code> file.
-          This provides the relevant output matchers (i.e. 
-          **.html, **.pdf, **.slides), it is mounted before any of the default 
-          matchers for Forrest and so can override this default behaviour.</p>
+          <p>
+            Output plugins provide a new output format. For example, the s5
+            plugin extends Forrest to produce HTML slides from Forrest
+            documents.
+          </p>
+          <p>
+            An output plugin provides an <code>output.xmap</code> file. This
+            provides the relevant output matchers (i.e. **.html, **.pdf,
+            **.slides), it is mounted before any of the default matchers for
+            Forrest and so can override this default behaviour.
+          </p>
         </section>
-        
         <section id="internalPlugins">
           <title>Internal Plugins</title>
-          
-          <p>Internal plugins are for advanced use only. They provide ways 
-          of extending or overriding Forrest's
-          internal operations. For example, the IMSManifest plugin
-          allows Forrest projects to use an IMS Manifest file instead of 
-          a site.xml and tabs.xml configuration files.</p>
-          
-          <p>Internal plugins provide an <code>internal.xmap</code> file. 
-          This provides the infrastructure matchers (i.e. 
-          site.xml, faq.xml, issues.xml), and will be mounted before 
-          *any* of the Forrest matches. This sitemap can override any behaviour 
-          within Forrest and so developers of these plugins must be especially
-          careful with the construction of their matchers, since they will be
-          processed before any other matchers and consequently can easily break
-          existing functionality. You must only do a &lt;map:generate ...&gt;
-          if you are certain you are going to process the full result. </p>
+          <p>
+            Internal plugins are for advanced use only. They provide ways of
+            extending or overriding Forrest's internal operations. For example,
+            the IMSManifest plugin allows Forrest projects to use an IMS
+            Manifest file instead of a site.xml and tabs.xml configuration
+            files.
+          </p>
+          <p>
+            Internal plugins provide an <code>internal.xmap</code> file. This
+            provides the infrastructure matchers (i.e. site.xml, faq.xml,
+            issues.xml), and will be mounted before *any* of the Forrest
+            matches. This sitemap can override any behaviour within Forrest and
+            so developers of these plugins must be especially careful with the
+            construction of their matchers, since they will be processed before
+            any other matchers and consequently can easily break existing
+            functionality. You must only do a &lt;map:generate ...&gt; if you
+            are certain you are going to process the full result.
+          </p>
         </section>
       </section>
-      
       <section>
         <title>Naming Conventions</title>
-        <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>
-        
-        <p>The name should be structured like a java package name, and should
-        include a relevant reverse domain name. For example:</p>
-        
+        <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>
+        <p>
+          The name should be structured like a java package name, and should
+          include a relevant reverse domain name. For example:
+        </p>
         <source>org.apache.forrest.plugin.PLUGIN_TYPE.PLUGIN_NAME</source>
         <source>net.sf.forrestPlugins.PLUGIN_TYPE.PLUGIN_NAME</source>
-        
-        <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:plugins/using">Using Plugins</a> for more 
-        information.</warning>
-        
+        <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:plugins/using">Using Plugins</a> for
+          more information.
+        </warning>
       </section>
-      
       <section>
         <title>An Example Plugin</title>
-  
-        <p>In order to fully understand the applicability of Forrest Plugins we 
-        will consider an extension to the way in which Forrest defines the 
-        structure of the site. By default Forrest uses a site.xml file to 
-        define navigation through the site and a tabs.xml file to define the 
-        tabs across the top of the page. But what if we want to use a different
-        file to describe site structure? For example, what if we want to use an
-        IMS Manifest file from the SCORM content package standards 
-        (http://www.adlnet.org/).</p>
-  
-        <p>An IMS Manifest file describes the structure of a site. It is also 
-        possible to define a set of rules for extracting tab information from 
-        such a file. Consequently, it is possible to use an IMSManifest file to 
-        create Forrest's site.xml and tabs.xml files. The advantage would be that
-        we can then use SCORM compliant content objects within Forrest.</p>
-  
-        <p>Unfortunately, IMS Manifests are much more complex than site.xml and 
-        tabs.xml files. Therefore, not all users will want to use them. Adding 
-        the functionality as an optional plugin seems to be the ideal 
-        solution.</p>
+        <p>
+          In order to fully understand the applicability of Forrest Plugins we
+          will consider an extension to the way in which Forrest defines the
+          structure of the site. By default Forrest uses a site.xml file to
+          define navigation through the site and a tabs.xml file to define the
+          tabs across the top of the page. But what if we want to use a
+          different file to describe site structure? For example, what if we
+          want to use an IMS Manifest file from the SCORM content package
+          standards (http://www.adlnet.org/).
+        </p>
+        <p>
+          An IMS Manifest file describes the structure of a site. It is also
+          possible to define a set of rules for extracting tab information from
+          such a file. Consequently, it is possible to use an IMSManifest file
+          to create Forrest's site.xml and tabs.xml files. The advantage would
+          be that we can then use SCORM compliant content objects within
+          Forrest.
+        </p>
+        <p>
+          Unfortunately, IMS Manifests are much more complex than site.xml and
+          tabs.xml files. Therefore, not all users will want to use them. Adding
+          the functionality as an optional plugin seems to be the ideal
+          solution.
+        </p>
       </section>
     </section>
-
     <section>
       <title>What Does a Forrest Plugin Look Like?</title>
-
-      <p>Plugins will need to conform to a specified directory structure. 
-      This mirrors the default forrest directory structure:</p>
-
-<source>
+      <p>
+        Plugins will need to conform to a specified directory structure. This
+        mirrors the default forrest directory structure:
+      </p>
+      <source>
 [plugin_name]
   |
   |-- plugin control files (xmap etc.)
@@ -191,15 +200,13 @@
       |
       `-- stylesheets (XSLs etc.)
 </source>
-  
-    <section>
-      <title>The IMS Manifest Plugin</title>
-
-      <p>If we consider the IMS Manifest Plugin described above, we see that we
-      will need the following files and directory structure:</p>
-
-     
-<source>
+      <section>
+        <title>The IMS Manifest Plugin</title>
+        <p>
+          If we consider the IMS Manifest Plugin described above, we see that we
+          will need the following files and directory structure:
+        </p>
+        <source>
 org.apache.forrest.plugin.internal.IMSManifest
   |
   |-- sitemap.xmap
@@ -213,12 +220,13 @@
                     |- pathutils.xsl
                     |- repositoryUtils.xsl
 </source>
-
-      <p>The sitemap.xmap file will override the default behaviour for the 
-      navigation generation matchers in Forrest, for example, it contains 
-      a matcher as follows:</p>
-
-<source><![CDATA[
+        <p>
+          The sitemap.xmap file will override the default behaviour for the
+          navigation generation matchers in Forrest, for example, it contains a
+          matcher as follows:
+        </p>
+        <source>
+<![CDATA[
 <map:match pattern="abs-menulinks">
   <map:select type="exists">
     <map:when test="{properties:content.xdocs}imsmanifest.xml">
@@ -237,32 +245,34 @@
   </map:when>
   </map:select>
 </map:match>
-]]></source>
-
-      <note>Note that this matcher will default to the behaviour provided by 
-      Forrest if there is no imsmanifest.xml file present in the project.
-      At present it is necessary to copy this default behaviour from the original
-      Forrest *.xmap files. We hope to improve on this in the future.</note>
+]]>
+        </source>
+        <note>
+          Note that this matcher will default to the behaviour provided by
+          Forrest if there is no imsmanifest.xml file present in the project. At
+          present it is necessary to copy this default behaviour from the
+          original Forrest *.xmap files. We hope to improve on this in the
+          future.
+        </note>
+      </section>
     </section>
-  </section>
-
-  <section>
-    <title>How does Installation work?</title>
-    <p>
-      See the 
-      <a href="site:plugins/using">Using Plugins</a>
-      for an overview of how the plugin installation system works and the places and order
-      that will be searched.
-    </p>
-    
-    <p>When Forrest installs a plugin it downloads a zip of the plugin code and 
-    extracts it into the <code>plugins</code> directory of Forrest and an entry is made 
-    in a temporary sitemap that manages plugins for your content object.
-    For example, installing the 
-    IMSManifest plugin described above will result in the following entry 
-    being added to the this temporary sitemap:</p>
-
-  <source><![CDATA[
+    <section>
+      <title>How does Installation work?</title>
+      <p>
+        See the <a href="site:plugins/using">Using Plugins</a> for an overview
+        of how the plugin installation system works and the places and order
+        that will be searched.
+      </p>
+      <p>
+        When Forrest installs a plugin it downloads a zip of the plugin code and
+        extracts it into the <code>plugins</code> directory of Forrest and an
+        entry is made in a temporary sitemap that manages plugins for your
+        content object. For example, installing the IMSManifest plugin described
+        above will result in the following entry being added to the this
+        temporary sitemap:
+      </p>
+      <source>
+<![CDATA[
 <map:select type="exists">
   <map:when test="output.xmap">
     <map:mount uri-prefix="" 
@@ -271,19 +281,21 @@
       pass-through="true"/>
   </map:when>
 </map:select>
-  ]]></source>
-  
-    <p>To be more accurate, the entries are made in one of three temporary
-    sitemaps, input.xmap, output.xmap and resources.xmap. These temporary
-    sitemaps are rebuilt each time the content object is built or run, thus
-    we are always guarenteed of having the right plugins installed.</p>
-    
+  ]]>
+      </source>
+      <p>
+        To be more accurate, the entries are made in one of three temporary
+        sitemaps, input.xmap, output.xmap and resources.xmap. These temporary
+        sitemaps are rebuilt each time the content object is built or run, thus
+        we are always guarenteed of having the right plugins installed.
+      </p>
+    </section>
+    <section>
+      <title>Further Reading</title>
+      <p>
+        If you want to build a plugin you might like to start with our
+        <a href="site:buildPlugin">HowTo on Building Plugins</a>.
+      </p>
     </section>
-
-	<section>
-		<title>Further Reading</title>
-		<p>If you want to build a plugin you might like to start with our 
-		<a href="site:buildPlugin">HowTo on Building Plugins</a>.</p>
-	</section>
   </body>
 </document>

Modified: forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- 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 Mon Apr  9 20:48:52 2007
@@ -16,118 +16,160 @@
   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>
-
+      <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 id="available">
         <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>
+        <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 id="install">
       <title>How is a Plugin Installed?</title>
-        <section id="required">
-          <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,</p>
-           <source>project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook</source>
-           <p>
-           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 has that property configured
-           to include some plugins. Currently there is only one to generate
-           PDF output from your source documents.</note>
-        </section>
-        <section id="version">
-          <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 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>
+      <section id="required">
+        <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,
+        </p>
+        <source>project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook</source>
+        <p>
+          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 has that property configured to
+          include some plugins. Currently there is only one to generate PDF
+          output from your source documents.
+        </note>
+      </section>
+      <section id="version">
+        <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 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>
+      </section>
+      <section id="sources">
+        <title>Where does Forrest look for Plugins sources?</title>
+        <section>
+          <title>Overview</title>
+          <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
+            <code>project.required.plugins.src</code> property, which is defined
+            in the <code>forrest.properties</code> file. By default this is set
+            to
+            <code>${forrest.home}/plugins,${forrest.home}/whiteboard/plugins</code>,
+            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:
+            <code>project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins</code>
+          </p>
+          <p>
+            You can add this line to your projects
+            <code>forrest.properties</code> file. However, it may be more
+            convenient to add it to a <code>forrest.properties</code> file in
+            your users home directory.
+          </p>
         </section>
-        <section id="sources">
-          <title>Where does Forrest look for Plugins sources?</title>
-          
-          <section>
-            <title>Overview</title>
-            
-            <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 <code>project.required.plugins.src</code>
-            property, which is defined in the <code>forrest.properties</code> file. By default
-            this is set to <code>${forrest.home}/plugins,${forrest.home}/whiteboard/plugins</code>,
-            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: 
-            <code>project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins</code></p>
-            
-            <p>You can add this line to your projects <code>forrest.properties</code> file. However,
-            it may be more convenient to add it to a <code>forrest.properties</code> file
-            in your users home directory.</p>
-          </section>
-          
-          <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 (<code>project.required.plugins.src</code> 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 (<code>project.required.plugins.src</code> 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 (<code>project.required.plugins.src</code> 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 : <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,</p>
-          <source>project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins</source>
-           <p>
-           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"
+        <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 (<code>project.required.plugins.src</code> 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 (<code>project.required.plugins.src</code> 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 (<code>project.required.plugins.src</code> 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 : <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,
+        </p>
+        <source>project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins</source>
+        <p>
+          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"
@@ -137,82 +179,103 @@
     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,</p>
-          <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>
-          <p>
-          will add the project specific plugins descriptors file <code>file:///${project.home}/plugins/plugins.xml</code> to the list of descriptors.</p>
-        </section>
+</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,
+        </p>
+        <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>
+        <p>
+          will add the project specific plugins descriptors file
+          <code>file:///${project.home}/plugins/plugins.xml</code> to the list
+          of descriptors.
+        </p>
       </section>
+    </section>
     <section id="local-deploy">
       <title>Editing plugins sources to enhance functionality</title>
-      
-      <note>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.</note>
-      
-      <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="site:contrib/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>
+      <note>
+        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.
+      </note>
+      <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="site:contrib/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>
     </section>
-    
     <section id="no-plugins">
       <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 to 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>
+      <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 to 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 id="conflict">
       <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>
+      <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 id="more">
       <title>Further Reading</title>
       <ul>

Modified: forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml (original)
+++ forrest/trunk/site-author/content/xdocs/procedures/How_to_publish_docs.xml Mon Apr  9 20:48:52 2007
@@ -18,69 +18,88 @@
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
   "http://forrest.apache.org/dtd/document-v20.dtd">
 <document>
-    <header>
-        <title>How to Publish Forrest Documentation</title>
-        <abstract>This documents the steps that the Documentation Coordinator should follow to update the Forrest
-            Website.</abstract>
-    </header>
-    <body>
-
-        <fixme author="open">This is work in progress!</fixme>
-        <section id="About">
-          <title>Introduction</title>
-          <p>All documentation about Apache Forrest is managed as a Forrest-built project located in the
-              site-author directory of forrest/trunk SVN. The Apapce Forrest website is updated by generating static pages from
-              the site-author-project and committing them to the forrest/site SVN, which is then
-              'svn checkout' on the forrest.apache.org webserver to create the website.</p>
-          <p>
-            See other notes for the Documentation Coordinator <a href="site:roles">role</a>.
-          </p>
-        </section>
-        <section id="forrestbot-local">
-          <title>Updating the site with a local forrestbot</title>
-          <p>Do once, create $FORREST_HOME/deploy.svn.settings file. These 
-            credentials are needed by forrestbot so that it can do your 'svn add' 
-            and 'svn commit' etc. to the forrest/site/ repository. The 
-            deploy.svn.settings file looks like:</p>
-          <source><![CDATA[<?xml version="1.0"?>
+  <header>
+    <title>How to Publish Forrest Documentation</title>
+    <abstract>
+      This documents the steps that the Documentation Coordinator should follow
+      to update the Forrest Website.
+    </abstract>
+  </header>
+  <body>
+    <fixme author="open">
+      This is work in progress!
+    </fixme>
+    <section id="About">
+      <title>Introduction</title>
+      <p>
+        All documentation about Apache Forrest is managed as a Forrest-built
+        project located in the site-author directory of forrest/trunk SVN. The
+        Apapce Forrest website is updated by generating static pages from the
+        site-author-project and committing them to the forrest/site SVN, which
+        is then 'svn checkout' on the forrest.apache.org webserver to create the
+        website.
+      </p>
+      <p>
+        See other notes for the Documentation Coordinator
+        <a href="site:roles">role</a>.
+      </p>
+    </section>
+    <section id="forrestbot-local">
+      <title>Updating the site with a local forrestbot</title>
+      <p>
+        Do once, create $FORREST_HOME/deploy.svn.settings file. These
+        credentials are needed by forrestbot so that it can do your 'svn add'
+        and 'svn commit' etc. to the forrest/site/ repository. The
+        deploy.svn.settings file looks like:
+      </p>
+      <source>
+<![CDATA[<?xml version="1.0"?>
 <project>
     <property name="deploy.svn.user" value="myApacheUsername"/>
     <property name="deploy.svn.password" value="myPassword"/>
-</project>]]> </source>
-          <p>Generating and publishing the main docs is very easy using a local forrestbot:
-          </p>
-
-          <source>cd site-author
+</project>]]>
+      </source>
+      <p>
+        Generating and publishing the main docs is very easy using a local
+        forrestbot:
+      </p>
+      <source>cd site-author
 forrest -f publish.xml build
 forrest -f publish.xml deploy</source>
-          <p>This builds the documentation locally then deploys it by committing
-            it to the <a href="https://svn.apache.org/repos/asf/forrest/site">forrest/site SVN</a>.
-            Then a cronjob on the server will automatically publish it. However, if
-            instant turnaround is required, then do this:
-          </p>
-          <source>ssh people.apache.org
+      <p>
+        This builds the documentation locally then deploys it by committing it
+        to the
+        <a href="https://svn.apache.org/repos/asf/forrest/site">forrest/site
+        SVN</a>. Then a cronjob on the server will automatically publish it.
+        However, if instant turnaround is required, then do this:
+      </p>
+      <source>ssh people.apache.org
 cd /www/forrest.apache.org
 svn update</source>
-          <p>
-            Publishing documentation for a particular plugin is done by:
-          </p>
-          <source>cd plugins/myPluginName
+      <p>
+        Publishing documentation for a particular plugin is done by:
+      </p>
+      <source>cd plugins/myPluginName
 $FORREST_HOME/tools/ant/bin/ant deploy-docs</source>
-          <p>
-            See further information in the 
-            <a href="site:buildPlugin">buildPlugin</a> doc.
-          </p>
-          <p>See some general notes about managing
-            <a href="http://www.apache.org/dev/project-site.html">project websites</a>.
-          </p>
-        </section>
-
-        <section id="OrgDoc">
-            <title>original docs</title>
-            <p>There have been a few explantions of our docs processing on the forrest-dev mail list.
-              Need to glean the info from them. Here is the content of some:</p>
-            <source>
-                <![CDATA[
+      <p>
+        See further information in the
+        <a href="site:buildPlugin">buildPlugin</a> doc.
+      </p>
+      <p>
+        See some general notes about managing
+        <a href="http://www.apache.org/dev/project-site.html">project
+        websites</a>.
+      </p>
+    </section>
+    <section id="OrgDoc">
+      <title>original docs</title>
+      <p>
+        There have been a few explantions of our docs processing on the
+        forrest-dev mail list. Need to glean the info from them. Here is the
+        content of some:
+      </p>
+      <source>
+<![CDATA[
                 To publish from trunk/site-author/
                 
                 Do once:
@@ -128,25 +147,26 @@
                 The second word is treated as an ant target to be called.
                 Just leave it out and forrestbot will use a default message.
                  ]]>
-            </source>
-        <p>Some more notes that need to be integrated above ...
-        </p>
-        <p>Note that forrestbot does not remove docs from the forrest/site SVN (FOR-392).
-          So need to manually delete: 'cd /svn/forrest/site; svn delete oldDoc'.
-          Then remove it from the forrestbot work directories:
-          'cd $FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm work/svn-deploy/forrest-docs/oldDoc'.
-        </p>
-        <p>
-The generated docs are in build/forrest-docs
-which is the name given to it in the forrestbot descriptor (site-author/publish.xml).
-Here is a trick for reviewing changes that forrestbot is ready to deploy ...
-        </p>
-        <source>
+      </source>
+      <p>
+        Some more notes that need to be integrated above ...
+      </p>
+      <p>
+        Note that forrestbot does not remove docs from the forrest/site SVN
+        (FOR-392). So need to manually delete: 'cd /svn/forrest/site; svn delete
+        oldDoc'. Then remove it from the forrestbot work directories: 'cd
+        $FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm
+        work/svn-deploy/forrest-docs/oldDoc'.
+      </p>
+      <p>
+        The generated docs are in build/forrest-docs which is the name given to
+        it in the forrestbot descriptor (site-author/publish.xml). Here is a
+        trick for reviewing changes that forrestbot is ready to deploy ...
+      </p>
+      <source>
 forrest -f publish.xml build
 svn update work/svn-deploy/forrest-docs
 diff -rq build/forrest-docs work/svn-deploy/forrest-docs | grep -v "\.svn" | grep differ</source>
-        </section>
-
-
-    </body>
+    </section>
+  </body>
 </document>



Mime
View raw message