Add the ability to generate a skeletal doc on the taglib(s) provided by plugins

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

plugin/plugin.jelly

@@ -93,6 +93,7 @@
     <attainGoal name="plugin:generate-navigation" />
     <attainGoal name="plugin:generate-goals" />
     <attainGoal name="plugin:generate-properties" />
+    <attainGoal name="plugin:generate-tags" />
   </goal>
 
   <!-- generate a skeletal navigation.xml for the plugin specified
@@ -198,6 +199,43 @@
     </j:if>
   </goal>
   
+  <!-- generate a skeletal tags.xml for the plugin specified -->
+  <goal name="plugin:generate-tags"
+    description="Generate tags.xml for the plugin">
+
+    <j:set var="skip" value="false" />
+    <j:set var="fileName">${maven.docs.src}/tags.xml</j:set>
+    <u:available file="${fileName}">
+      <echo>Skipping file as '${fileName}' already exists</echo>
+      <j:set var="skip" value="true" />
+    </u:available>
+
+    <j:if test="${!skip}">
+      <j:set var="pluginScript" value="false" />
+      <u:available file="${basedir}/plugin.jelly">
+        <j:set var="pluginScript" value="true" />
+      </u:available>
+
+      <mkdir dir="${maven.docs.src}" />
+
+      <j:if test="${!pluginScript}">
+        <!-- no plugin.jelly - generate a file for empty goals -->
+        <echo>No plugin.jelly, not generating tags.xml</echo>
+      </j:if>
+
+      <j:if test="${pluginScript}">
+        <echo>Generating file '${fileName}'</echo>
+        <!-- generate docs based on plugin.jelly -->
+        <j:useBean class="org.apache.maven.plugin.PluginToTags" 
+          pluginScript="${basedir}/plugin.jelly"
+          xdoc="${fileName}"
+          var="xformer"/>
+        ${xformer.transform()}
+      </j:if>
+
+    </j:if>
+  </goal>
+
   <goal name="plugin:download" description="download and install a plugin from a remote repo" prereqs="plugin:download-artifact">
     <plugin:uninstall name="${artifactId}" />
     <u:file var="localPlugin" name="${maven.plugin.dir}/${artifactId}-${version}.jar" />

plugin/project.xml

@@ -91,6 +91,12 @@
     </developer>
   </developers>
   <dependencies>
+    <dependency>
+      <groupId>commons-lang</groupId>
+      <artifactId>commons-lang</artifactId>
+      <version>2.0</version>
+      <url>http://jakarta.apache.org/commons/lang/</url>
+    </dependency>
     <dependency>
       <groupId>commons-jelly</groupId>
       <artifactId>commons-jelly-tags-xml</artifactId>
@@ -102,5 +108,32 @@
       <artifactId>commons-jelly-tags-interaction</artifactId>
       <version>20030211.143817</version>
     </dependency>
+    <dependency>
+      <groupId>jdom</groupId>
+      <artifactId>jdom</artifactId>
+      <version>b10</version>
+    </dependency>
+    <dependency>
+      <groupId>saxpath</groupId>
+      <artifactId>saxpath</artifactId>
+      <version>1.0-FCS</version>
+    </dependency>
+    <dependency>
+      <groupId>jaxen</groupId>
+      <artifactId>jaxen</artifactId>
+      <version>1.0-FCS-full</version>
+    </dependency>
+    <dependency>
+      <groupId>xml-apis</groupId>
+      <artifactId>xml-apis</artifactId>
+      <version>1.0.b2</version>
+      <url>http://xml.apache.org/xerces2-j/</url>
+    </dependency>
+    <dependency>
+      <id>xerces</id>
+      <version>2.4.0</version>
+      <url>http://xml.apache.org/xerces2-j/</url>
+    </dependency>
   </dependencies>
 </project>
+

plugin/src/main/org/apache/maven/plugin/PluginToTags.java

@@ -0,0 +1,197 @@
+package org.apache.maven.plugin;
+
+/*
+ * ====================================================================
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed 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.
+ * ====================================================================
+ */
+
+import org.apache.commons.lang.StringUtils;
+import org.jdom.Document;
+import org.jdom.Element;
+import org.jdom.JDOMException;
+import org.jdom.input.SAXBuilder;
+import org.jdom.xpath.XPath;
+
+import java.io.BufferedWriter;
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Map;
+
+public class PluginToTags
+{
+    /** plugin script */
+    private String pluginScript;
+
+    /** output file */
+    private String xdoc;
+
+    /**
+     * @return Returns the outputFile.
+     */
+    public String getXdoc()
+    {
+        return xdoc;
+    }
+
+    /**
+     * @param outputFile
+     *            The outputFile to set.
+     */
+    public void setXdoc(String outputFile)
+    {
+        this.xdoc = outputFile;
+    }
+
+    /**
+     * @return Returns the pluginScript.
+     */
+    public String getPluginScript()
+    {
+        return pluginScript;
+    }
+
+    /**
+     * @param pluginScript
+     *            The plugin script to generate the docs from.
+     */
+    public void setPluginScript(String pluginScript)
+    {
+        this.pluginScript = pluginScript;
+    }
+
+    /**
+     * Transform the plugin script to the output file. The output file will be
+     * in xdoc format.
+     * 
+     * @throws IOException reading files
+     * @throws JDOMException on xml
+     */
+    public void transform() throws JDOMException, IOException
+    {
+        File output = new File(getXdoc());
+        BufferedWriter bw = new BufferedWriter(new FileWriter((output)));
+        bw.write("<document>\n");
+        bw.write("  <properties>\n");
+        bw.write("    <title>Plugin tags</title>\n");
+        bw.write("  </properties>\n");
+        bw.write("  <body>\n");
+        List taglibs = getTaglibs();
+        writeOverview(bw, taglibs);
+        writeTaglibs(bw, taglibs);
+        bw.write("  </body>\n");
+        bw.write("</document>\n");
+        bw.close();
+    }
+    
+    /**
+     * Write xdoc sections to the given writer for each taglib
+     * @param bw the writer
+     * @param taglibs a list of taglibs to output
+     * @throws IOException when there are errors writing
+     */
+    private void writeTaglibs(BufferedWriter bw, List taglibs) throws IOException
+    {
+        for (Iterator taglibIter = taglibs.iterator(); taglibIter.hasNext();)
+        {
+            Map taglib = (Map) taglibIter.next();
+            bw.write("    <section name='" + taglib.get("uri") + " Tag Library'>\n");
+            List tagNames = (List)taglib.get("tagNames");
+            // write out subsection with name, description, attr, desc etc....
+            for (Iterator tagIter = tagNames.iterator(); tagIter.hasNext();)
+            {
+                String name = (String) tagIter.next();
+                bw.write("      <subsection name='" + name + " Tag'>\n");
+                bw.write("        <p>No description</p>\n");
+                bw.write("        <table>\n");
+                bw.write("          <tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>\n");
+                bw.write("        </table>\n");
+                bw.write("      </subsection>\n");
+            }
+            bw.write("    </section>\n");
+        }
+    }
+
+    /**
+     * Write an xdoc overview section for all taglibs
+     * @param bw the writer for output
+     * @param taglibs the taglibs to output
+     * @throws IOException when writing fails
+     */
+    private void writeOverview(BufferedWriter bw, List taglibs) throws IOException
+    {
+        bw.write("    <section name='Overview'>\n");
+        bw.write("      <p>The following tag libraries and tags are provided by this plugin.</p>\n");
+        bw.write("      <ol>\n");
+        for (Iterator taglibIter = taglibs.iterator(); taglibIter.hasNext();)
+        {
+            Map taglib = (Map) taglibIter.next();
+            String title = taglib.get("uri") + " Tag Library";
+            String linkStart = "<a href='#" + StringUtils.replace(title, " ", "_")
+            	+ "'>";
+            bw.write("        <li>" + linkStart + taglib.get("uri") + "</a>\n");
+            bw.write("          <ol>\n");
+            List tagNames = (List)taglib.get("tagNames");
+            for (Iterator tagIter = tagNames.iterator(); tagIter.hasNext();)
+            {
+                String name = (String) tagIter.next();
+                bw.write("            <li><a href='#" + name + "_Tag'>" + name + "</a></li>\n");
+            }
+            bw.write("          </ol>\n");
+            bw.write("        </li>\n");
+        }    
+        bw.write("      </ol>\n");
+        bw.write("    </section>\n");
+    }
+
+    /**
+     * @return a list of tag libraries. Each element in the list 
+     * is a {@link Map}. Each map contains an entry for "uri" (as a String)
+     * and one for tagNames (as a List).
+     * 
+     * @throws IOException reading files
+     * @throws JDOMException on xml
+     */
+    public List getTaglibs() throws JDOMException, IOException
+    {
+        SAXBuilder builder = new SAXBuilder();
+        Document doc = builder.build(new File(getPluginScript()));
+        XPath xpath = XPath.newInstance("/project/define:taglib");
+        List taglibElements = xpath.selectNodes(doc);
+        List taglibs = new LinkedList();
+        for (Iterator iter = taglibElements.iterator(); iter.hasNext();)
+        {
+            Element element = (Element) iter.next();
+            Map taglib = new HashMap();
+            taglib.put("uri", element.getAttributeValue("uri"));
+            taglib.put("tagNames", new LinkedList());
+            XPath tagsXp = XPath.newInstance("define:tag|define:jellybean");
+            List tagsElements = tagsXp.selectNodes(element);
+            for (Iterator tagsIter = tagsElements.iterator(); tagsIter.hasNext();)
+            {
+                Element tagsElement = (Element) tagsIter.next();
+                ((List) taglib.get("tagNames")).add(tagsElement.getAttributeValue("name"));
+            }
+            taglibs.add(taglib);
+        }
+        return taglibs;
+    }
+
+}

plugin/src/plugin-test/maven.xml

@@ -28,7 +28,7 @@
 
     <assert:assertFileExists file="${maven.docs.src}"/>
 
-	<u:tokenize var="fileList" delim=",">navigation.xml,goals.xml</u:tokenize>
+	<u:tokenize var="fileList" delim=",">navigation.xml,goals.xml,properties.xml,tags.xml</u:tokenize>
 
 	<j:forEach var="file" items="${fileList}">
 	  <assert:assertFileExists file="${maven.docs.src}/${file}"/>

plugin/src/plugin-test/plugin.jelly

@@ -20,6 +20,7 @@
 
 <project>
   
+  
   <goal name="goal1"
     description="Build a plugin jar and install to the maven.repo.local">
 

plugin/src/test/org/apache/maven/plugin/PluginToTagsTest.java

@@ -0,0 +1,75 @@
+package org.apache.maven.plugin;
+
+/*
+ * ====================================================================
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed 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.
+ * ====================================================================
+ */
+
+import junit.framework.TestCase;
+import org.jdom.JDOMException;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.Map;
+
+/**
+ * @author Dion Gillard
+ */
+public class PluginToTagsTest extends TestCase
+{
+    private static final String basedir = System.getProperty("basedir");
+
+    /**
+     * test the right taglibs are found 
+     * @throws JDOMException
+     * @throws IOException
+     */
+    public void testTaglibs() throws JDOMException, IOException
+    {
+        PluginToTags instance = new PluginToTags();
+        testBasedir();
+        instance.setPluginScript(basedir + "/src/test/plugin.jelly");
+        assertEquals("wrong number of taglibs", 1, instance.getTaglibs().size());
+        Map taglib = (Map)instance.getTaglibs().get(0);
+        assertEquals("bad taglib uri", "doc", taglib.get("uri"));
+    }
+
+    /**
+     * test that basedir is passed in
+     */
+    public void testBasedir()
+    {
+        assertNotNull("no basedir", basedir);
+    }
+
+    /**
+     * test the taglibs are written as a file
+     * @throws JDOMException
+     * @throws IOException
+     */
+    public void testTransform() throws JDOMException, IOException
+    {
+        PluginToTags instance = new PluginToTags();
+        testBasedir();
+        instance.setPluginScript(basedir + "/src/test/plugin.jelly");
+        instance.setXdoc(basedir + "/target/tags.xml");
+        instance.transform();
+        File outputFile = new File(instance.getXdoc());
+        assertTrue("xdoc not generated", outputFile.exists());
+    }
+
+
+}

plugin/src/test/plugin.jelly

@@ -0,0 +1,778 @@
+<?xml version="1.0"?>
+<!-- 
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed 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.
+ */
+ -->
+
+
+<project xmlns:define="jelly:define"
+  xmlns:j="jelly:core"
+  xmlns:jsl="jelly:jsl"
+  xmlns:log="jelly:log"
+  xmlns:maven="jelly:maven"
+  xmlns:pom="pom"
+  xmlns:util="jelly:util"
+  xmlns:x="jelly:xml"
+  xmlns:velocity="jelly:velocity"
+  xmlns:doc="doc">
+
+  <j:new var="reports" className="java.util.ArrayList"/>
+
+
+  <define:taglib uri="doc">
+    <define:tag name="deregisterReport">
+      <!-- @name : Report to deregister, must be same as name used to register -->
+      
+      <maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
+      
+      <j:set var="removeRpt" value="null"/>
+      <j:forEach var="rpt" items="${reports}">
+        <j:if test="${rpt.get('name').equals(name)}">
+          <j:set var="removeRpt" value="${rpt}"/>  
+        </j:if>
+      </j:forEach>
+      <j:if test="${removeRpt != null}">
+        <j:set var="dummy" value="${reports.remove(removeRpt)}"/>
+      </j:if>
+    </define:tag>
+    
+    <define:tag name="registerReport">
+      <!--
+      @name the name of this report. Used for navigation items
+      @pluginName the name of the plugin.  @plugin:report goal must exist
+      @description text description of report
+      @link the nav-bar link for this report
+      @target the target for the new page (_self, _blank, ...) 
+      -->
+      <maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
+
+      <!-- check if the given name is in the list already -->      
+      <j:set var="add" value="true"/>
+      <j:forEach var="rpt" items="${reports}">
+        <j:if test="${rpt.get('name').equals(name)}">
+          <j:set var="add" value="false"/>  
+        </j:if>
+      </j:forEach>
+      
+      <j:if test="${add.equals('true')}">
+        <j:new var="report" className="java.util.HashMap"/>
+        <j:set var="dummy">
+          ${report.put('name', name)}
+          ${report.put('pluginName', pluginName)}
+          ${report.put('description', description)}
+          ${report.put('link', link)}
+          ${report.put('externalLink', externalLink)}
+          ${report.put('target', target)}
+          ${reports.add(report)}
+        </j:set>
+      </j:if>
+
+    </define:tag>
+    
+    <define:tag name="formatAsNumber">
+      <!--
+       | @string
+       | @pattern
+      -->
+      
+      <!-- This appears to need to be here which is no good. Need
+           more of a global tool box.
+      -->
+      
+      <j:useBean var="formatter" class="org.apache.maven.util.DVSLFormatter"/>
+      ${formatter.formatNumber(string,pattern)}
+    </define:tag>
+
+    <define:tag name="jslFile">
+      <!--
+       | Basic tag for performing arbitrary jsl transformations
+       | on arbitrary jsl inputs.
+       | @input (optional)
+       | @output
+       | @stylesheet
+       | @encoding
+       | @omitXmlDeclaration
+       | @outputMode
+       | @prettyPrint
+      -->
+ 
+      <!-- Set default encoding if not set. -->
+      <j:if test="${encoding == null}">
+        <j:set var="encoding" 
+               value="${plugin.getVariable('maven.docs.outputencoding')}"/>
+      </j:if>
+
+      <j:if test="${input != null}">    
+        <util:file name="${input}" var="inputFile" />
+        <x:parse var="doc" xml="${inputFile}"/>
+      </j:if>
+      
+      <j:set var="stylesheetURI" value="file:${stylesheet}"/>
+      <j:file
+        name="${output}"
+        encoding="${encoding}"
+        omitXmlDeclaration="${omitXmlDeclaration}"
+        outputMode="${outputMode}"
+        prettyPrint="${prettyPrint}">
+        <j:include uri="${stylesheetURI.toString()}"/>
+      </j:file>
+    
+    </define:tag>
+    
+    
+    <define:tag name="jsl">
+      <!--
+       | This tag has a lot of defaults suitable for transforming
+       | documents easily. See jslCore for a tag suitable for
+       | transforming documents how you want.
+       | @input
+       | @outputDirectory - Will be placed under ${maven.gen.docs}
+       | @stylesheet
+       | @encoding           - defaults to ${maven.docs.outputencoding}
+       | @omitXmlDeclaration - defaults to ${maven.docs.omitXmlDeclaration}
+       | @outputMode
+       | @prettyPrint
+      -->
+    
+      <!-- 
+      @todo make sure the output directory exists.
+      -->        
+      
+      <!-- Set default outputDirectory if not set. -->
+      <j:if test="${empty(outputDirectory)}">
+        <j:set var="outputDirectory"  value="${maven.gen.docs}"
+        />
+      </j:if>
+
+      <!-- Set default encoding if not set. -->
+      <j:if test="${encoding == null}">
+        <j:set var="encoding" value="${maven.docs.outputencoding}" />
+      </j:if>
+      
+      <j:if test="${omitXmlDeclaration == null}">
+        <j:set var="omitXmlDeclaration" value="${maven.docs.omitXmlDeclaration}"/>
+      </j:if>
+      
+      <mkdir dir="${outputDirectory}"/>
+
+      <doc:jslFile
+        input="${input}"
+        output="${outputDirectory}/${output}"
+        stylesheet="${stylesheet}"
+        encoding="${encoding}"
+        omitXmlDeclaration="${omitXmlDeclaration}"
+        outputMode="${outputMode}"
+        prettyPrint="${prettyPrint}"/>
+    </define:tag>
+
+
+      <!--
+        @link
+        @relativePath
+        @name
+        @img
+        @state - expanded / collapsed / none
+        @target
+        -->
+    <define:tag name="itemLink">
+      <x:element name="a">
+        <x:attribute name="href">${pathTool.calculateLink(link,relativePath)}</x:attribute>
+        <j:choose>
+          <j:when test="${target != null and target.equals('_blank')}">
+            <x:attribute name="class">newWindow</x:attribute>
+            <x:attribute name="title">New Window</x:attribute>
+          </j:when>
+          <j:when test="${link.startsWith('http')}">
+            <x:attribute name="class">externalLink</x:attribute>
+            <x:attribute name="title">External Link</x:attribute>
+          </j:when>
+        </j:choose>
+        <j:if test="${!empty(target)}">
+          <x:attribute name="target">${target}</x:attribute>
+        </j:if>
+        <j:if test="${empty(state)}"><j:set var="state" value="none"/></j:if>
+        <j:if test="${empty(img)}">${name}</j:if>
+        <j:if test="${!empty(img)}"><img style="border: 1px" src="${pathTool.calculateLink(img,relativePath)}" title="${name}" alt="${name}"/></j:if>
+      </x:element>
+    </define:tag>
+    
+    <define:tag name="text-xdoc">
+      <!--
+        @output - The output file
+        @title - Title for page
+        @section - Section heading
+        @encoding - The XML encoding
+        @preamble - Placed in paragraph block prior to text
+        @inputText - Will be wrapped in a CDATA, will not escape CDATA tags (as yet)
+        @inputFile - Will be read in and wrapped in CDATA. Overrides inputText if set
+        -->
+      <j:set var="inputFile">${inputFile}</j:set>
+      <j:if test="${inputFile != ''}">
+        <util:file name="${inputFile}" var="inputFileObject"/>
+        <util:loadText var="inputText" file="${inputFileObject}"/>
+       </j:if>
+        
+      <!-- Set default encoding if not set. -->
+        <j:if test="${encoding == null}">
+          <j:set var="encoding" 
+                 value="${plugin.getVariable('maven.docs.outputencoding')}"/>
+        </j:if>
+      
+      
+      <j:file name="${output}" prettyPrint="false" encoding="${encoding}">         
+            <document>
+              <properties><title>${title}</title></properties>
+              <body>
+                <section name="${section}">
+                <p>${preamble}</p>
+                  <source>
+                    <![CDATA[${inputText}]]>
+                  </source>
+                </section>
+              </body>
+            </document>
+    </j:file>  
+    </define:tag>
+
+    <!-- Alternator for row style in a table -->
+    <define:tag name="printRow">
+      <j:if test="${(count % 2) gt 0}">
+        <x:element name="tr">
+          <x:attribute name="class">a</x:attribute>
+        </x:element>
+      </j:if>
+      <j:if test="${(count % 2) le 0}">
+        <x:element name="tr">
+          <x:attribute name="class">b</x:attribute>
+        </x:element>
+      </j:if>
+    </define:tag>
+
+    <!-- Generates the JSL files on the given srcdir attribute -->
+    <define:tag name="performJSL">
+      <util:file var="srcdirFile" name="${srcdir}"/>
+      <j:set var="srcdir" value="${srcdirFile.getCanonicalPath()}"/>
+      <util:file var="destdirFile" name="${destdir}"/>
+      <j:set var="destdir" value="${destdirFile.getCanonicalPath()}"/>
+       
+      <util:replace var="fromPattern" oldChar="\" newChar="/" value="${srcdir}/*.xml"/>
+      <util:replace var="toPattern" oldChar="\" newChar="/" value="${destdir}/*.html"/>
+      <j:if test="${mapper == null}">
+        <j:new var="mapper" className="org.apache.maven.util.CaseInsensitiveGlobPatternMapper"/>
+      </j:if>
+      <j:setProperties object="${mapper}" from="${fromPattern}" to="${toPattern}"/>
+
+      <util:replace var="fromDirPattern" oldChar="\" newChar="/" value="${srcdir}*"/>
+      <util:replace var="toDirPattern" oldChar="\" newChar="/" value="${destdir}*"/>
+      <j:new var="dirMapper" className="org.apache.maven.util.CaseInsensitiveGlobPatternMapper"/>
+      <j:setProperties object="${dirMapper}" from="${fromDirPattern}" to="${toDirPattern}"/>
+
+      <fileScanner var="docFiles">
+        <fileset dir="${srcdir}">
+          <patternset>
+            <exclude name="**/project.xml"/>
+            <exclude name="**/template.xml"/>
+            <exclude name="**/navigation.xml"/>
+            <exclude name="changes.xml"/>
+            <include name="**/*.xml"/>
+          </patternset>
+        </fileset>
+      </fileScanner>
+
+      <!-- determine nav file to be used:- 1. check for sitewide nav files -->
+      <!-- supplied nav file as project.xml in stylesheets dir -->
+      <util:available file="${maven.docs.src}/stylesheets/project.xml">
+        <util:file var="siteNavFile" name="${maven.docs.src}/stylesheets/project.xml"/>
+      </util:available>
+      <!-- supplied nav file as project.xml in root of xdocs source tree -->
+      <util:available file="${maven.docs.src}/project.xml">
+        <util:file var="siteNavFile" name="${maven.docs.src}/project.xml"/>
+      </util:available>
+      <!-- supplied navigation file in root of xdocs source tree -->
+      <util:available file="${maven.docs.src}/navigation.xml">
+        <util:file var="siteNavFile" name="${maven.docs.src}/navigation.xml"/>
+      </util:available>
+      <!-- navigation file that was generated -->
+      <util:available file="${maven.gen.docs}/navigation.xml"> 
+        <util:file var="siteNavFile" name="${maven.gen.docs}/navigation.xml"/> 
+      </util:available> 
+      <!-- hold onto maven.docs.src for later -->
+      <util:file var="docsSrcFile" name="${maven.docs.src}"/>
+
+      <!-- parse the project nav. Someone jellier than me can remove the temp file requirement -->
+      <maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
+
+      <util:file var="tempnav" name="${maven.build.dir}/project-nav.xml"/>
+    
+      <j:file name="${tempnav.toString()}" outputMode="xml">
+        <j:import file="${plugin.resources}/navigation.jelly" inherit="true"/>    
+      </j:file>
+  
+      <x:parse var="projectNavRoot" xml="${tempnav}"/>
+      <x:set var="projectNav" select="$projectNavRoot/project"/>
+
+      <j:forEach var="file" items="${docFiles.iterator()}">
+
+        <util:replace var="inDirForward" oldChar="\" newChar="/" value="${file.parent}"/>
+        <j:set var="outDir" value="${dirMapper.mapFileName(inDirForward).0}"/>
+        <mkdir dir="${outDir}"/>
+
+        <!-- generate output file name -->
+        <util:replace var="outFileForward" oldChar="\" newChar="/" value="${file.toString()}"/>
+        <j:set var="outFile" value="${mapper.mapFileName(outFileForward).0}"/>
+
+        <echo>Generating ${outFile} from ${file}</echo>
+        <!-- work out relative path -->
+        <util:replace var="docsForward" oldChar="\" newChar="/" value="${srcdir}"/>
+        <j:if test="${pathTool == null}">
+            <j:useBean var="pathTool" class="org.apache.maven.util.DVSLPathTool"/>
+        </j:if>
+        <j:set var="relativePath" value="${pathTool.getRelativePath(docsForward, outFileForward)}"/>
+
+        <!-- determine nav file to be used: 2. check for nav file -->
+        <!-- in the same directory as xml file being processed -->
+        <!-- if no such nav file available use sitewide nav file -->
+        <j:set var="navFile" value="${siteNavFile}" />
+        <util:available file="${file.parentFile.absoluteFile}/navigation.xml">
+          <!-- dont use current directory navigation.xml if it's in maven.docs.src -->
+          <j:if test="${!(file.parentFile.equals(docsSrcFile))}">
+            <util:file var="navFile" name="${file.parentFile.absoluteFile}/navigation.xml"/>
+          </j:if>
+        </util:available>
+
+        <!-- parse nav and make it available to the stylesheet -->
+        <x:parse var="navXML" xml="${navFile}"/>
+        <x:set var="nav" select="$navXML/project"/>
+        <!-- parse the doc and pass it to the stylesheet -->
+        <x:parse var="doc" xml="${file}"/>
+        
+        <j:file name="${outFile}" encoding="${outputencoding}"
+          omitXmlDeclaration="true" outputMode="xml"
+          prettyPrint="no">
+          <j:include uri="${stylesheet.toString()}"/>
+        </j:file>
+      </j:forEach>
+
+    </define:tag>
+    
+    
+    <define:tag name="jslToSite">
+        <!--
+         | transforms files in the given dir using the site stylesheet and navigation and place them
+         | in maven.docs.dest (typically target/docs)
+         | @srcdir source directory
+        -->
+  
+      <maven:param-check value="${srcdir}" fail="true" message="'srcdir' must be specified"/>
+
+      <maven:pluginVar var="maven.xdoc.jsl" 
+        plugin='maven-xdoc-plugin' property='maven.xdoc.jsl' />
+      
+      <!-- copy old value for restoring it later -->
+      <j:set var="previous.plugin.resources" value="${plugin.resources}" />
+
+      <maven:pluginVar var="plugin.resources" 
+        plugin='maven-xdoc-plugin' property='plugin.resources' />
+        
+      <maven:pluginVar var="includeProjectDocumentation" 
+        plugin='maven-xdoc-plugin' property='maven.xdoc.includeProjectDocumentation' />
+        
+      <maven:pluginVar var="maven.xdoc.poweredby.image" 
+        plugin='maven-xdoc-plugin' property='maven.xdoc.poweredby.image' />
+        
+      <maven:pluginVar var="maven.xdoc.poweredby.title" 
+        plugin='maven-xdoc-plugin' property='maven.xdoc.poweredby.title' />
+        
+      <maven:pluginVar var="maven.xdoc.poweredby.url" 
+        plugin='maven-xdoc-plugin' property='maven.xdoc.poweredby.url' />
+        
+      <maven:pluginVar var="maven.xdoc.crumb.separator" 
+        plugin='maven-xdoc-plugin' property='maven.xdoc.crumb.separator' />
+      
+      <j:set var="outputDirectory" value="${maven.gen.docs}" />
+      <j:set var="stylesheet" value="file:${plugin.resources}/site.jsl" />
+  
+      <j:set var="outputencoding" value="${maven.docs.outputencoding}" />
+  
+      <doc:performJSL srcdir="${srcdir}" destdir="${maven.docs.dest}" />
+
+      <!-- restore plugin.resources -->
+      <j:set var="plugin.resources" value="${previous.plugin.resources}" />
+
+    </define:tag>
+    
+    <!--
+     | escapes a string for generating a valid name token (need for "name" attribute in html anchors)
+     | @value given token
+    --> 
+     <define:tag name="escapeNameToken">
+     <j:invokeStatic var="escapedtoken" className="org.apache.commons.lang.StringUtils" method="replaceChars">
+        <j:arg type="java.lang.String" value="${value}" useContextClassLoader="true"/>
+        <j:arg type="java.lang.String" value=" .,;!?/'\()[]{}+*°" useContextClassLoader="true"/>
+        <j:arg type="java.lang.String" value="__________________" useContextClassLoader="true"/>
+     </j:invokeStatic>${escapedtoken}</define:tag>
+
+  </define:taglib>
+
+  <!-- ================================================================== -->
+  <!-- P R O J E C T  D O C U M E N T A T I O N                           -->
+  <!-- ================================================================== -->
+
+  <goal name="xdoc"
+    prereqs="xdoc:generate-from-pom, xdoc:transform"
+    description="Generate html project documentation xdoc sources"/>
+
+  <goal name="xdoc:init"
+    description="Generates the directory structure required for xdocs">
+
+    <mkdir dir="${maven.gen.docs}"/>
+    <mkdir dir="${maven.docs.dest}"/>
+
+  </goal>
+
+  <goal
+    name="xdoc:generate-from-pom"
+    prereqs="xdoc:init, xdoc:register-reports"
+    description="Generates xdocs for site based on project descriptor">
+    
+    <echo>Generating xdocs from POM ... </echo>
+    
+    <util:tokenize var="pomDocuments" delim=",">${maven.xdoc.pomDocuments}</util:tokenize>
+    
+    <!-- All the templates use $project for now. -->
+    <j:set var="project" value="${pom}"/>
+    <maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
+
+    <!-- Does the user want the maven-generated docs on their site? -->
+    <j:set 
+      var="includeProjectDocumentation" 
+      value="${maven.xdoc.includeProjectDocumentation}"/>
+    
+    <!-- Need the escaper to html output. -->
+    <j:useBean var="escape" class="org.apache.velocity.anakia.Escape"/>
+    <j:useBean var="files" class="org.apache.velocity.texen.util.FileUtil"/>
+    
+    <!-- Need to enrich information about dependency by taking some information from its POM. -->
+    <j:useBean var="dependencyDescriber" class="org.apache.maven.DependencyDescriberBean"/>
+     ${dependencyDescriber.build(pom)}
+    
+    
+    <j:if test="${encoding == null}">
+         <j:set 
+           var="encoding" 
+           value="${maven.docs.outputencoding}"
+         />
+    </j:if>
+    
+    <j:forEach var="pomDocument" items="${pomDocuments}">
+
+      <!-- If the template ends with ".xml" use velocity to generate the 
+           HTML. If it ends with ".jelly" use JSL. -->
+      <j:choose>
+        <j:when test="${pomDocument.endsWith('.xml')}">
+          <velocity:merge 
+            name="${maven.gen.docs}/${pomDocument}"
+            basedir="${plugin.resources}/templates"
+            template="${pomDocument}"
+            inputEncoding="${encoding}"
+            outputEncoding="${encoding}" 
+          />
+        </j:when>
+        <j:when test="${pomDocument.endsWith('.jelly')}">
+          <doc:jslFile
+            output="${maven.gen.docs}/${pomDocument.substring(0,pomDocument.indexOf('.jelly'))}.xml"
+            stylesheet="${plugin.resources}/templates/${pomDocument}"
+            outputMode="xml"
+            prettyPrint="true"/>
+        </j:when>
+        <j:otherwise>
+          <fail>Unknown report format for report [${pomDocument}].</fail>
+        </j:otherwise>
+      </j:choose>
+      
+    </j:forEach>
+
+  </goal>
+
+  <!-- ================================================================== -->
+  <!-- V A L I D A T E  X D O C S                                         -->
+  <!-- ================================================================== -->
+
+  <!-- validate xdocs -->
+  <goal name="xdoc:validate" prereqs="pom:taglib"
+    description="Validate xdocs match the schema">
+
+    <available file="${maven.docs.src}" type="dir"
+      property="maven.docs.src.available"/>
+
+    <j:if test="${maven.docs.src.available}">
+      <fileScanner var="navFiles">
+        <fileset dir="${maven.docs.src}">
+          <patternset>
+            <include name="**/navigation.xml"/>
+          </patternset>
+        </fileset>
+      </fileScanner>
+
+      <j:forEach var="file" items="${navFiles.iterator()}">
+        <echo>Validating ${file}</echo>
+        <pom:validate validator="${maven.home}/maven-navigation-1.0.xsd"
+          projectDescriptor="${file}"/>
+      </j:forEach>
+    </j:if>
+  </goal>
+
+  <!-- ================================================================== -->
+  <!-- C O P Y  R E S O U R C E S                                         -->
+  <!-- ================================================================== -->
+
+  <!-- copy resources needed for xdocs -->
+  <goal name="xdoc:copy-resources"
+    prereqs="xdoc:init"
+    description="copy static resources for use in xdocs generated html">
+    
+    <!-- Read in the ui properties. -->
+    <util:properties uri="file:${plugin.resources}/ui.properties" var="uiProperties"/>
+
+    <!-- Copy maven supplied stylesheets.  -->
+    <copy todir="${maven.docs.dest}/style" overwrite="yes" filtering="yes">
+      <fileset dir="${plugin.resources}/css">
+        <include name="**/*.css"/>
+      </fileset>
+      
+      <filterset>
+        <j:forEach var="uiProperty" items="${uiProperties.keys()}">
+          <util:replace var="token" oldChar="." newChar="_" value="${uiProperty}"/>
+          <j:set var="token" value="${token.substring(6).toUpperCase()}"/>
+           <!-- Check if User has overidden this property -->
+           <j:set var="propertyName" value="${uiProperty}" />
+           <j:set var="propertyValue" value="${context.getVariable(propertyName)}"/>
+           <j:choose>
+             <j:when test="${propertyValue != null}">
+               <!-- Use user's properties -->
+               <filter token="${token}" value="${propertyValue}"/>
+             </j:when>
+             <j:otherwise>
+               <!-- Use plugin's default properties -->
+               <filter token="${token}" value="${uiProperties.getProperty(uiProperty)}"/>
+             </j:otherwise>
+           </j:choose>
+        </j:forEach>
+      </filterset>
+    </copy>
+
+    <!-- Copy maven supplied images.  -->
+    <copy todir="${maven.docs.dest}/images" overwrite="yes" filtering="no">
+      <fileset dir="${plugin.resources}/images">
+        <include name="**/*.gif"/>
+        <include name="**/*.jpeg"/>
+        <include name="**/*.jpg"/>
+        <include name="**/*.png"/>
+      </fileset>
+    </copy>
+
+  </goal>
+
+  <!-- ================================================================== -->
+  <!-- C O P Y  U S E R  S U P P L I E D  R E S O U R C E S               -->
+  <!-- ================================================================== -->
+
+  <!-- copy user resources -->
+  <goal name="xdoc:copy-user-resources"
+    prereqs="xdoc:init"
+    description="Copy user provided resources to docs destination">
+
+    <j:if test="${maven.docs.src.available}">
+
+      <!-- Copy user supplied resources -->
+      <copy todir="${maven.docs.dest}" filtering="no">
+        <fileset dir="${maven.docs.src}">
+          <exclude name="**/*.xml"/>
+          <exclude name="**/*.fml"/>
+          <exclude name="**/CVS/*"/>
+          <exclude name="stylesheets/*"/>
+        </fileset>
+        <!-- copy file in generated docs folder: this allows for reporting plugins to add images -->
+        <fileset dir="${maven.gen.docs}">
+          <exclude name="**/*.xml"/>
+          <exclude name="**/CVS/*"/>
+          <exclude name="stylesheets/*"/>
+        </fileset>
+      </copy>
+
+      <util:available file="${maven.docs.src}/stylesheets">
+        <!-- Copy user supplied stylesheets, can override maven -->
+        <copy todir="${maven.docs.dest}/style" overwrite="true" filtering="no">
+          <fileset dir="${maven.docs.src}/stylesheets">
+            <include name="**/*.css"/>
+          </fileset>
+        </copy>
+      </util:available>
+ 
+    </j:if>
+  </goal>
+
+  <!-- ================================================================== -->
+  <!-- D V S L  D O C U M E N T A T I O N                                 -->
+  <!-- ================================================================== -->
+  
+  <goal name="xdoc:transform"
+    prereqs="xdoc:init"
+    description="Generate html project documentation xdoc sources">
+
+    <tstamp>
+      <format property="mavenCurrentYear" pattern="yyyy"/>
+    </tstamp>
+
+    <!-- Use jelly utils here -->
+
+    <available
+      file="${maven.gen.docs}"
+      type="dir"
+      property="maven.gen.docs.available"
+    />
+
+    <available
+      file="${maven.docs.src}"
+      type="dir"
+      property="maven.docs.src.available"
+    />
+
+    <!-- use JSL in Jelly to build the documenation -->
+    <attainGoal name="xdoc:copy-resources"/>
+    <attainGoal name="xdoc:copy-user-resources"/>
+    <attainGoal name="xdoc:jelly-transform"/>
+
+  </goal>
+
+  <!-- ================================================================== -->
+  <!-- J E L L Y   D O C U M E N T A T I O N                              -->
+  <!-- ================================================================== -->
+
+  <goal name="xdoc:jelly-init" description="Set up jelly xdoc requirements">
+    <!-- moving here temporarily -->
+    <tstamp>
+      <format property="mavenCurrentYear" pattern="yyyy"/>
+    </tstamp>
+    <tstamp>
+      <format property="build.date" pattern="${maven.xdoc.date.format}"
+        locale="${maven.xdoc.date.locale}"/>
+    </tstamp>
+  </goal>
+  
+  
+
+  <goal name="xdoc:register-reports">
+    <!--
+     | We need to have each <report> register itself with us so we can
+     | build up our navbar.  To do this, we call the plugin:register
+     | goal on each report plugin.
+     |-->
+     
+    <j:if test="${!pom.reports.isEmpty()}">
+      <j:forEach var="report" items="${pom.reports}">
+        <attainGoal name="${report}:register"/>
+      </j:forEach>
+    </j:if>
+    
+    <!-- If the descriptor is empty, use these as defaults -->
+    <j:if test="${pom.reports.isEmpty()}">
+      <attainGoal name="maven-jdepend-plugin:register"/>
+      <attainGoal name="maven-checkstyle-plugin:register"/>
+      <attainGoal name="maven-changes-plugin:register"/>
+      <attainGoal name="maven-changelog-plugin:register"/>
+      <attainGoal name="maven-developer-activity-plugin:register"/>
+      <attainGoal name="maven-file-activity-plugin:register"/>
+      <attainGoal name="maven-license-plugin:register"/>
+      <attainGoal name="maven-javadoc-plugin:register"/>
+      <attainGoal name="maven-jxr-plugin:register"/>
+      <attainGoal name="maven-junit-report-plugin:register"/>
+      <attainGoal name="maven-linkcheck-plugin:register"/>
+      <attainGoal name="maven-tasklist-plugin:register"/>
+    </j:if>
+  </goal>
+
+  <goal name="xdoc:jelly-transform" 
+    prereqs="xdoc:init, xdoc:jelly-init, xdoc:register-reports"
+    description="transform xdocs using jelly/jsl rather than dvsl">
+
+    <j:set var="destdir" value="${maven.docs.dest}"/>
+    <j:set var="outputencoding" value="${maven.docs.outputencoding}"/>
+
+    <!-- need to parse navigation into $nav -->
+
+    <!-- mapper for determining output file name -->
+    <j:new var="mapper" className="org.apache.maven.util.CaseInsensitiveGlobPatternMapper"/>
+    
+
+    <!-- path tool for relative processing -->
+    <j:useBean var="pathTool" class="org.apache.maven.util.DVSLPathTool"/>
+
+    <!-- tool for loading resources from the class loader -->
+    <j:useBean class="org.apache.maven.util.ResourceBean" var="resourceTool"/>
+
+    <!-- determine which stylesheet to use -->
+    <j:set var="stylesheet" value="${maven.xdoc.jsl}"/>
+    <j:if test="${empty(stylesheet)}">
+      <j:set var="stylesheet" value="${resourceTool.findResource('plugin-resources/site.jsl')}"/>
+      <j:if test="${empty(stylesheet)}">
+        <log:warn>Could not load the JSL stylesheet 'site.jsl' on the classpath</log:warn>
+        <j:set var="stylesheet" value="./site.jsl"/>
+      </j:if>
+    </j:if>
+
+    <util:available file="${maven.gen.docs}">
+      <log:info>About to use JSL stylesheet ${stylesheet}</log:info>
+
+      <!-- perform JSL on generated docs -->
+      <doc:performJSL srcdir="${maven.gen.docs}" destdir="${maven.docs.dest}"/>
+    </util:available>
+    
+    <!-- perform JSL on user provided docs -->
+    <j:if test="${maven.docs.src.available}">
+      <log:info>
+        Transforming user supplied documentation.
+      </log:info>
+      <doc:performJSL srcdir="${maven.docs.src}" destdir="${maven.docs.dest}"/>
+    </j:if>
+
+  </goal>
+  
+  
+  <!-- 
+   ! This is required as the linkchecker runs as a final pass over the generated
+   ! document tree.
+   ! FIXME: Why isn't this in linkcheck?
+   !-->
+  <goal name="xdoc:performJSL"
+      description="Allows the LinkCheck plugin to xdoc a single directory">
+
+    <maven:pluginVar var="maven.xdoc.src" plugin="maven-linkcheck-plugin" property="maven.xdoc.src" />
+    <doc:performJSL 
+      srcdir="${maven.xdoc.src}" 
+      destdir="${maven.docs.dest}"/>
+  </goal>
+  
+  <goal name="xdoc:dump-report-settings">
+    <echo>Dumping report settings</echo>
+    <maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
+       
+    <j:forEach var="report" items="${reports}">
+      <echo>Report: ${report}</echo>  
+    </j:forEach>
+  </goal>
+
+</project>

plugin/xdocs/navigation.xml

@@ -27,6 +27,7 @@
     <menu name="Overview">
       <item href="/goals.html" name="Goals"/>
       <item href="/properties.html" name="Properties"/>
+      <item href="/tags.html" name="Tags"/>
     </menu>
   </body>
 </project>

plugin/xdocs/tags.xml

@@ -0,0 +1,113 @@
+<document>
+  <properties>
+    <title>Plugin tags</title>
+    <author email="dion@apache.org">dIon Gillard</author>
+  </properties>
+  <body>
+    <section name='Overview'>
+      <p>The following tag libraries and tags are provided by this plugin.</p>
+      <ol>
+        <li><a href='#plugin_Tag_Library'>plugin</a>
+          <ol>
+            <li><a href='#uninstall_Tag'>uninstall</a></li>
+            <li><a href='#clearCache_Tag'>clearCache</a></li>
+          </ol>
+        </li>
+        <li><a href='#assert_Tag_Library'>assert</a>
+          <ol>
+            <li><a href='#assertFileExists_Tag'>assertFileExists</a></li>
+            <li><a href='#assertFileNotFound_Tag'>assertFileNotFound</a></li>
+            <li><a href='#assertEquals_Tag'>assertEquals</a></li>
+          </ol>
+        </li>
+      </ol>
+    </section>
+
+    <section name='plugin Tag Library'>
+      <subsection name='uninstall Tag'>
+        <p>
+          A tag to uninstall a given plugin from the various plugin directories, including
+          <ol>
+            <li><code>${maven.plugin.dir}</code></li>
+            <li><code>${maven.plugin.user.dir}</code></li>
+            <li><code>${maven.plugin.unpacked.dir}</code></li>
+          </ol>
+        </p>
+        <table>
+          <tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
+          <tr>
+            <td>name</td>
+            <td>No</td>
+            <td>Usually this is <code>${pom.artifactId}</code></td>
+          </tr>
+        </table>
+      </subsection>
+      <subsection name='clearCache Tag'>
+        <p>
+          Clears the files used for caching plugin goals, dependencies and 
+          tag libraries from <code>${maven.plugin.unpacked.dir}</code>
+        </p>
+        <p>There are no attributes for this tag</p>
+      </subsection>
+    </section>
+    <section name='assert Tag Library'>
+      <p>
+        This tag library is typically used in testing plugins. And are
+        similar in usage to the assert methods in a JUnit test case.
+      </p>
+      <subsection name='assertFileExists Tag'>
+        <p>Fails the build if the given file does not exist, otherwise no effect.</p>
+        <table>
+          <tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
+          <tr>
+            <td>file</td>
+            <td>No</td>
+            <td>The path of the file to be checked</td>
+          </tr>
+          <tr>
+            <td>msg</td>
+            <td>Yes</td>
+            <td>A message to be displayed when the file doesn't exist</td>
+          </tr>
+        </table>
+      </subsection>
+      <subsection name='assertFileNotFound Tag'>
+        <p>Fails the build if the given file does exist, otherwise no effect.</p>
+        <table>
+          <tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
+          <tr>
+            <td>file</td>
+            <td>No</td>
+            <td>The path of the file to be checked</td>
+          </tr>
+          <tr>
+            <td>msg</td>
+            <td>Yes</td>
+            <td>A message to be displayed when the file doesn't exist</td>
+          </tr>
+        </table>
+      </subsection>
+      <subsection name='assertEquals Tag'>
+        <p>Fails the build if the two values are not equal, otherwise no effect.</p>
+        <table>
+          <tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
+          <tr>
+            <td>expected</td>
+            <td>No</td>
+            <td>The expected value</td>
+          </tr>
+          <tr>
+            <td>value</td>
+            <td>No</td>
+            <td>The actual value</td>
+          </tr>
+          <tr>
+            <td>msg</td>
+            <td>Yes</td>
+            <td>A message to be displayed when the values aren't equal.</td>
+          </tr>
+        </table>
+      </subsection>
+    </section>
+  </body>
+</document>