add documentation for ant mojo

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

maven-plugin-plugin/src/it/ant-basic/src/main/scripts/touch.build.xml

@@ -20,7 +20,7 @@
   -->
 <!-- START SNIPPET: ant-build -->
 <project>
-  <target name="touch">
+  <target name="touch-file">
     <touch mkdirs="true" file="target/${name}"/>
   </target>
 </project>

maven-plugin-plugin/src/it/ant-basic/src/main/scripts/touch.mojos.xml

@@ -19,10 +19,13 @@
   ~ under the License.
   -->
 <!-- START SNIPPET: ant-mojo -->
-<pluginMetadata xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 ../../../../../../maven-plugin-tools-model/target/generated-site/xsd/plugin-metadata-1.0.0.xsd ">
+<pluginMetadata xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/plugin-metadata-1.0.0.xsd">
   <mojos>
     <mojo>
-      <call>touch</call>
+      <!-- target name to call in ant script -->
+      <call>touch-file</call>
+      <!-- mojo goal name -->
       <goal>touch</goal>
       <parameters>
         <parameter>

maven-plugin-plugin/src/site/apt/examples/ant-mojo.apt.vm

@@ -0,0 +1,81 @@
+ ------
+ Writing an Ant Maven plugin
+ ------
+ Olivier Lamy
+ ------
+ 2012-05-14
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements.  See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership.  The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License.  You may obtain a copy of the License at
+~~
+~~   http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied.  See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Writing an Ant Maven plugin
+
+  You can write Maven plugins based on ant scripts.
+
+* Pom configuration
+
++------------
+  ...
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-script-ant</artifactId>
+      <version>2.2.1</version>
+    </dependency>
+  </dependencies>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-plugin-plugin</artifactId>
+        <version>${project.version}</version>
+        <dependencies>
+          <dependency>
+            <groupId>org.apache.maven.plugin-tools</groupId>
+            <artifactId>maven-plugin-tools-ant</artifactId>
+            <version>${project.version}</version>
+          </dependency>
+        </dependencies>
+      </plugin>
+    </plugins>
+  </build>
+  ...
++------------
+
+* Files structure
+
+  The Ant consists of two files. If you want to create a touch mojo, you must have:
+
+  * src/main/scripts/touch.mojos.xml (contains Mojo descriptor informations)
+
+  * src/main/scripts/touch.build.xml (contains the Ant xml to execute)
+
+** Ant Mojo descriptor
+
+  File src/main/scripts/touch.mojos.xml
+
+%{snippet|id=ant-mojo|url=http://svn.apache.org/repos/asf/maven/plugin-tools/trunk/maven-plugin-plugin/src/it/ant-basic/src/main/scripts/touch.mojos.xml}
+
+** Ant script
+
+%{snippet|id=ant-build|url=http://svn.apache.org/repos/asf/maven/plugin-tools/trunk/maven-plugin-plugin/src/it/ant-basic/src/main/scripts/touch.build.xml}
+