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 <map:generate ...> - 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 <map:generate ...> 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>
