You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2005/04/03 09:26:24 UTC
svn commit: r159897 -
forrest/trunk/docs-author/content/xdocs/howto/howto-buildPlugin.xml
Author: crossley
Date: Sat Apr 2 23:26:23 2005
New Revision: 159897
URL: http://svn.apache.org/viewcvs?view=rev&rev=159897
Log:
Add section IDs. Minor text tweaks and some typos.
Modified:
forrest/trunk/docs-author/content/xdocs/howto/howto-buildPlugin.xml
Modified: forrest/trunk/docs-author/content/xdocs/howto/howto-buildPlugin.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/docs-author/content/xdocs/howto/howto-buildPlugin.xml?view=diff&r1=159896&r2=159897
==============================================================================
--- forrest/trunk/docs-author/content/xdocs/howto/howto-buildPlugin.xml (original)
+++ forrest/trunk/docs-author/content/xdocs/howto/howto-buildPlugin.xml Sat Apr 2 23:26:23 2005
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
- Copyright 2002-2004 The Apache Software Foundation or its licensors,
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
as applicable.
Licensed under the Apache License, Version 2.0 (the "License");
@@ -25,8 +25,8 @@
<abstract>This How-To describes the steps necessary to build a plugin for
Forrest. Forrest uses plugins to add new input formats, output formats
and to change its default behaviour. Since plugins are downloaded when
- needed and can be hosted at any location plugin code can be developed
- independantly of Apache Forrest. This how-to describes each of the major
+ needed and can be hosted at any location, plugin code can be developed
+ independently of Apache Forrest. This how-to describes each of the major
steps in creating a plugin and then works through some examples of
plugin creation in order to illustrate the materials.</abstract>
@@ -35,7 +35,7 @@
<audience title="Intended Audience">
<p>Users needing to add additional input formats or output formats or
- to change the way Forrest internals work.</p>
+ to change the operation of the Forrest internals.</p>
<warning>The Plugin Infrastructure is still at an early stage of design
and implementation, consequently this How-To <em>may</em> be out of date
@@ -75,7 +75,7 @@
</section>
- <section>
+ <section id="ant">
<title>Make ant Available on the Command Line</title>
<p>
The following instructions rely heavily on
@@ -92,7 +92,7 @@
</p>
</section>
- <section>
+ <section id="seed">
<title>Seed a New Plugin</title>
<p>Regardless of the type of plugin you are building, the directory
structure is almost identical, as are most of the requried
@@ -113,24 +113,24 @@
<note>Although you can name your project anything you like we do have
some <a href="site:documentation/developers/pluginInfrastructure">naming
- coventions</a> that we recomend you follow.</note>
+ coventions</a> that we recommend you follow.</note>
<note>If you plan on building your plugin elsewhere you can copy the
<code>build.xml</code> build file to your own plugin work directory and
use it there.</note>
<p>See
- <a href="site:documentation/developers/pluginInfrastructure">What Does
- a Forrest Plugin Look Like?</a> for more information on the plugin
+ <a href="site:documentation/developers/pluginInfrastructure">Plugin
+ Infrastructure</a> for more information about the plugin
directory structure and configuration files.</p>
- <section>
+ <section id="edit-template">
<title>Edit the Plugin Template</title>
<p>You now have a skeleton plugin project. However, it doesn't do
anything useful yet. Now is a good time to edit some of the files
provided. For example:</p>
- <section>
+ <section id="status">
<title>status.xml</title>
<p>This file is used to track changes to the plugin
project and to manage lists of things that still need to be done.
@@ -143,7 +143,7 @@
plugin.</p>
</section>
- <section>
+ <section id="forrest-properties">
<title>forrest.properties</title>
<p>This file defines many configuration parameters for Forrest. It
@@ -151,7 +151,7 @@
for more details.</p>
</section>
- <section>
+ <section id="skinconf">
<title>src/documentation/skinconf.xml</title>
<p>This configures the skin for your plugins documentation. There
are some items that need to be configured in here, for example, the
@@ -159,7 +159,7 @@
best to read through it, changing what you need to.</p>
</section>
- <section>
+ <section id="doc">
<title>Documentation</title>
<p>It is also a good idea to start writing the documentation at this
stage. The above process created a very simple plugin documentation
@@ -168,8 +168,8 @@
</section>
</section>
- <section>
- <title>Edit the Plugin XMap file(s)</title>
+ <section id="edit-sitemap">
+ <title>Edit the Plugin sitemap file(s)</title>
<p>The plugin <code>xmap</code> file is a Cocoon sitemap that is mounted
at a strategic place in the Forrest pipeline. It is in this file
that you will instruct Forrest how to operate. An input plugin
@@ -187,47 +187,47 @@
for some hints and tips on creating plugin sitemaps. In addition, as with
all development work on Forrest, you will find
the <a href="ext:forrest/mail-lists/forrest-dev">developer mailing list</a>
- a very doog resource (check the archives before posting, please).</p>
+ a very good resource (check the archives before posting, please).</p>
- <section>
+ <section id="components">
<title>Components, Actions and Resources</title>
<p>If your plugin uses any components (i.e. generators, transformers or
serializers), actions or resources they must
- be defined in either the plugins xmap or one of its parents. The parents
+ be defined in either the xmap for this plugin or one of its parents. The parents
of an <code>input.xmap</code> are <code>sitemap.xmap</code> and
<code>forrest.xmap</code>, whilst the parent of both
<code>output.xmap</code> and <code>internal.xmap</code> are
- <code>sitemap.xmap</code>.</p>
+ <code>sitemap.xmap</code></p>
<p>If you want to use the realpath where the sitemap.xmap of your plugin
- resides then you have to use
+ resides then you need to use
<code>{forrest:plugins}/PLUGIN_NAME</code> instead of <code>{realpath:/}</code>.
</p>
<p>See the examples below for more details.</p>
</section>
</section>
- <section>
+ <section id="resources">
<title>Create the Necessary Resource Files</title>
<fixme author="rdg">Discuss the XSL files and other such resources</fixme>
</section>
- <section>
+ <section id="samples">
<title>Create Samples in the Documentation</title>
<p>Plugin documentation should provide (as a minimum) an
index page that provides an overview and a set of samples that demonstrate
- the functionlaity of the plugin. Typically these samples will be
+ the functionality of the plugin. Typically these samples will be
provided in a <code>samples</code> subdirectory in the plugin
documentation and will be referenced from both <code>site.xml</code>
- and <code>tabs.xml</code>.</p>
+ and <code>tabs.xml</code> configuration files.</p>
<p>Try to provide a sample for all the major functions of your plugin
and document any configuration that is available.</p>
</section>
- <section>
+ <section id="test">
<title>Testing a Plugin</title>
<p>Since your documentation for the plugin illustrates all of its
- functionality you can use that site for testing the plugin. However, you
+ functionality, you can use that site for testing the plugin. However, you
must first deploy in your local install of Forrest. Each plugin contains
a buildfile that includes a <code>test</code> target. This target, by
default, builds the documtantion for your plugin.</p>
@@ -243,25 +243,25 @@
<p>It is also a really good idea to build proper tests for your
plugins using a suitable testing framework, for example,
- <a href="http://webtest.canoo.com/">WebTest</a>. We recomend that you
+ <a href="http://webtest.canoo.com/">WebTest</a>. We recommend that you
extend the <code>test</code> target in your plugins build file because
this target is also used when performing integration tests on Forrest.
- In addition, we recomend that you use the samples in your documentation
+ In addition, we recommend that you use the samples in your documentation
for your tests, this way you are documenting your plugin at the same time
as writing your tests.</p>
</section>
- <section>
+ <section id="release">
<title>Releasing a Plugin</title>
- <section>
+ <section id="register">
<title>Register the Plugin with Apache Forrest</title>
<fixme author="rdg">Describe the plugins.xml file</fixme>
<fixme author="rdg">Describe making a request of Forrest devs for
inclusion</fixme>
</section>
- <section>
+ <section id="deploy">
<title>Deploying the Plugin</title>
<p>To deploy the plugin so that others can use it, it must be made
available as a zip from the URL indicated in the
@@ -272,7 +272,7 @@
<code>ant deploy</code> from within the plugin directory.</p>
<p>This command will, by default, deploy to the Apache Forrest web site.
- In order to do this you need write access to Forrest. If you want to
+ In order to do this you need commit access to Forrest. If you want to
deploy your plugin to a different location you
can build the zip of your plugin with <code>ant dist</code>
and then copy the zip file from <code>build/dist</code> to wherever
@@ -281,7 +281,7 @@
<note>Running this command on any plugin will also deploy any
changes to the <code>plugins.xml</code> file. If you are deploying to
your own website you will have to request changes to the
- <code>plugins.xml</code> and have a Forrest committer publish the new
+ <code>plugins.xml</code> and ask the Forrest committers to publish the new
document.</note>
<warning>Running the <code>deploy</code> or <code>dist</code> targets
@@ -292,21 +292,21 @@
</section>
</section>
- <section>
+ <section id="examples">
<title>Examples</title>
<p>This section will provide some example plugins to help illustrate the
steps discussed above.</p>
- <section>
+ <section id="input">
<title>Input Plugin</title>
<fixme author="RDG">Discuss OpenOffice.org plugin here</fixme>
</section>
- <section>
+ <section id="output">
<title>Output Plugin</title>
<fixme author="RDG">Discuss s5 plugin here</fixme>
</section>
- <section>
+ <section id="internal">
<title>Internal Plugin</title>
<fixme author="RDG">Discuss IMSManifest plugin here</fixme>
</section>