o adding doco contributed by Bob Allison

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@306969 13f79535-47bb-0310-9956-ffa450edef68

maven-site/src/site/apt/guides/plugin/build-plugin.apt

@@ -0,0 +1,66 @@
+ ------
+ Plugin Development Guide - Building a Plugin
+ -----
+ Bob Allison
+ ------
+ 12 October 2005
+ ------
+ 
+
+Project Definition
+
+  Once the mojos have been written for the plugin, it is time to
+  build the plugin.  To do this properly, the project's descriptor
+  needs to have a number of settings set properly:
+
+*------------------+----------------------------------------------------------+
+|<<<groupId>>>     |This is the group ID for the plugin, and should match the |
+|                  |common prefix to the packages used by the mojos           |
+*------------------+----------------------------------------------------------+
+|<<<artifactId>>>  |This is the name of the plugin                            |
+*------------------+----------------------------------------------------------+
+|<<<version>>>     |This is the version of the plugin                         |
+*------------------+----------------------------------------------------------+
+|<<<packaging>>>   |This should be set to "<<<maven-plugin>>>"                |
+*------------------+----------------------------------------------------------+
+|<<<dependencies>>>|A dependency must be declared to the Maven Plugin Tools   |
+|                  |API to resolve "<<<AbstractMojo>>>" and related classes   |
+*------------------+----------------------------------------------------------+
+
+  Listed below is a POM for a plugin which uses the simple sample mojo:
+
++----+
+<project>
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>sample.plugin</groupId>
+  <artifactId>maven-hello-plugin</artifactId>
+  <packaging>maven-plugin</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <name>Sample Parameter-less Maven Plugin</name>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-plugin-tools-api</artifactId>
+      <version>2.0-beta-2</version>
+    </dependency>
+  </dependencies>
+</project>
++----+
+
+Build Goals
+
+  There are a few goals which are defined with the Maven plugin
+  packaging as part of a standard build lifecycle:
+
+*-------------+----------------------------------------------------+
+|<<<compile>>>|Compiles the Java code for the plugin and builds the|
+|             |plugin descriptor                                   |
+*-------------+----------------------------------------------------+
+|<<<test>>>   |Runs the plugin's unit tests                        |
+*-------------+----------------------------------------------------+
+|<<<package>>>|Builds the plugin jar                               |
+*-------------+----------------------------------------------------+
+|<<<install>>>|Installs the plugin jar in the local repository     |
+*-------------+----------------------------------------------------+
+|<<<deploy>>> |Deploys the plugin jar to the remote repository     |
+*-------------+----------------------------------------------------+

maven-site/src/site/apt/guides/plugin/first-mojo.apt

@@ -0,0 +1,66 @@
+ -------
+ Plugin Development Guide - Your First Mojo
+ -------
+ Bob Allison
+ -------
+ 12 October 2005
+ -------
+
+Your First Mojo
+
+  At its simplest, a Java mojo consists simply of a single class.  There is
+  no requirement for multiple classes like EJBs, although a plugin which
+  contains a number of similar mojos is likely to use an abstract
+  superclass for the mojos to consolidate code common to all mojos.
+
+  When processing the source tree to find mojos, the class
+  <<<org.apache.maven.tools.plugin.extractor.java.JavaMojoDescriptorExtractor>>>
+  looks for classes with a "<<<goal>>>" annotation on the class.  Any class
+  with this annotation are included in the plugin configuration file.
+
+A Simple Mojo
+
+  Listed below is a simple mojo class which has no parameters.  This is
+  about as simple as a mojo can be.  After the listing is a description
+  of the various parts of the source.
+
++---+
+package sample.plugin;
+
+import org.apache.maven.plugin.AbstractMojo;
+import org.apache.maven.plugin.MojoExecutionException;
+
+/**
+ * @goal sayhi
+ * @description Says "Hi" to the user
+ */
+public class GreetingMojo extends AbstractMojo {
+    public void execute() throws MojoExecutionException {
+        getLog().info("Hello, world.");
+    }
+}
++---+
+
+  * The class <<<org.apache.maven.plugin.AbstractMojo>>> provides most of the
+    infrastructure required to implement a mojo except for the
+    <<<execute>>> method.
+
+  * The comment lines starting with "<<<@goal>>>" and "<<<@description>>>"
+    are examples of annotations.  These two annotations are required, but
+    there are a number of annotations which can be used to control how and
+    when the mojo is executed.
+
+  * The <<<execute>>> method can throw two exceptions:
+
+    * <<<org.apache.maven.plugin.MojoExecutionException>>> if an unexpected
+      problem occurs.  Throwing this exception causes a "BUILD ERROR" message
+      to be displayed.
+
+    * <<<org.apache.maven.plugin.MojoFailureException>>> if an expected
+      problem (such as a compilation failure) occurs.  Throwing this exception
+      causes a "BUILD FAILURE" message to be displayed.
+
+  * The <<<getLog>>> method (defined in <<<AbstractMojo>>>) returns a
+    log4j-like logger object which allows plugins to create messages at levels
+    of "debug", "info", "warn", and "error".  This logger is the accepted means
+    to display information to the user.

maven-site/src/site/apt/guides/plugin/first-plugin.apt

@@ -0,0 +1,15 @@
+ -------
+ Plugin Development Guide - Your First Plugin
+ -------
+ Bob Allison
+ -------
+ 12 October 2005
+ -------
+
+Your First Plugin
+
+  This section of the document walks the reader through the process
+  of building a simple plugin which takes no parameters and simply
+  displays a message on the screen when run.  It covers the basics of
+  setting up a project to create a plugin, the minimal contents of a
+  Java mojo, and the means to cause the mojo to be executed.

maven-site/src/site/apt/guides/plugin/first-run.apt

@@ -0,0 +1,44 @@
+ ------
+ Plugin Development Guide - Executing Your First Mojo
+ ------
+ Bob Allison
+ ------
+ 12 October 2005
+ ------
+ 
+
+Executing Your First Mojo
+
+  The most direct means of executing your new plugin is to specify the
+  plugin goal directly on the command line.  To do this, you need to
+  specify a fully-qualified goal in the form of:
+
++----+
+groupID:artifactID:version:goal
++----+
+
+  For example, to run the simple mojo in the sample plugin, you would enter
+  "<<<m2 sample.plugin:maven-hello-plugin:1.0-SNAPSHOT:sayhi>>>" on the
+  command line.
+
+Shortening the Command Line
+
+  It is possible to shorten the amount of typing needed on the command
+  line.  To do this, you need to install the plugin with the
+  <<<updateReleaseInfo>>> option set to true; for example:
+
++----+
+m2 -DupdateReleaseInfo=true install
++----+
+
+  You also need to add your plugin's group ID to the list of group IDs
+  searched by default.  To do this, you need to add the following to
+  your <<<settings.xml>>> file:
+
++----+
+<pluginGroups>
+  <pluginGroup>sample.plugin</pluginGroup>
+</pluginGroups>
++----+
+
+  At this point, you can run the mojo with "<<<m2 hello:sayhi>>>".

maven-site/src/site/apt/guides/plugin/index.apt

@@ -0,0 +1,17 @@
+ ------
+ Plugin Development Guide - Introduction
+ ------
+ Bob Allison
+ ------
+ 12 October 2005
+ -----
+
+Introduction
+
+  This web site contains documentation to assist users in developing
+  their own plugins.  \xAB<Text like this are comments identifying known
+  problems with this documentation.  As the problems are fixed these
+  comments should be removed.>\xBB
+
+  \xAB<Should the plugin overview (at least the first part of it) be
+  repeated here for clarity?>\xBB