thanks again Bill Burton! all i can say is "wow!"

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271711 13f79535-47bb-0310-9956-ffa450edef68
24 years ago · 5578d94e01
--- a/proposal/xdocs/dvsl/build.xml
+++ b/proposal/xdocs/dvsl/build.xml
@@ -24,13 +24,20 @@
        <path refid="classpath"/>
      </classpath>
    </taskdef>
    <!-- Make stuff available relative to current location -->
    <mkdir dir="${basedir}/xdocs" />
    <copy todir="${basedir}/xdocs">
      <fileset dir="${docs.src}" includes="stylesheets/project.xml" />
    </copy>
  </target>

  <target name="taskdocs" depends="init"
          description="Generate Task Documentation">
    <dvsl basedir="${taskdocs.src}" destdir="${manual.dest}"
          style="task.dvsl" extension=".html" 
          includes="**/*.xml" />
          style="task.dvsl" extension=".html"
          includes="**/*.xml">
      <velconfig name="velocimacro.library" value="" />
    </dvsl>
  </target>

 </project>
--- a/proposal/xdocs/dvsl/task.dvsl
+++ b/proposal/xdocs/dvsl/task.dvsl
@@ -2,7 +2,7 @@
 *  DVSL Stylesheet to format the Ant Task documentation.
 *#

 #set( $relative-path = "." )
 #set( $relative-path = "../../" )
 #if (false)
 #set( $body-bg = '#ffffff' )
 #set( $body-fg = '#000000' )
@@ -44,115 +44,124 @@
 #if ( $test )$output#end
 #end

 #match( "task" )
  #set( $task_name = $attrib.name )
  ## Create task title with first letter in upper case
  #set( $task_title = "$task_name.substring(0,1).toUpperCase()$task_name.substring(1)" )
    <html>
    <head>
      <meta http-equiv="Content-Language" content="en-us">
      <title>$task_title Task</title>
    </head>

    <body bgcolor="$body-bg" text="$body-fg" link="$body-link"
          alink="$body-link" vlink="$body-link">

    <table border="0" width="100%" cellspacing="4">

      ## PAGE HEADER
      <tr>
        <td>

        ## JAKARTA LOGO
        <a href="http://jakarta.apache.org/">
          <img src="http://jakarta.apache.org/images/jakarta-logo.gif"
               align="left" alt="The Jakarta Project" border="0"/>
        </a>

        #if( $project.logo )

          #set( $alt = $project.logo )
          #set( $home = $project.attribute("href") )
          #set( $src = $project.logo.attribute( "href" ) )

          ## PROJECT LOGO
          <a href="$home">
            <img src="$src" align="right" alt="$alt" border="0"/>
          </a>
        #end
 ## Macro to capitalize a word making the first letter upper case
 #macro(capitalize $word)
 $word.substring(0,1).toUpperCase()$word.substring(1)
 #end

        </td>
      </tr>

      ## HEADER SEPARATOR
      <tr>
        ##<td colspan="2">
        <td>
 	  <hr noshade="" size="1"/>
        </td>
      </tr>

      <tr>
        <!-- RIGHT SIDE MAIN BODY -->
        <td  valign="top" align="left">
          $context.applyTemplates("long-description")
          $context.applyTemplates("structure/attributes")
          $context.applyTemplates("structure/elements")
        </td>
      </tr>
 #match( "task" )
  #set( $project = $node.selectSingleNode("document('xdocs/stylesheets/project.xml')/project" ) )
  #if ($node.name().equals("task"))
    #set( $title = "#capitalize($attrib.name) Task" )
    #set( $summary = $node.short-description )
  #end

 <html>
 <head>
  <meta http-equiv="Content-Language" content="en-us">
  <title>$title</title>
 </head>

 <body bgcolor="$body-bg" text="$body-fg" link="$body-link"
      alink="$body-link" vlink="$body-link">

 <table border="0" width="100%" cellspacing="4">

  <!-- PAGE HEADER -->
  <tr>
    <td>
      <table border="0" width="100%"><tr>
          <td valign="bottom">
            <font size="+3" face="arial,helvetica,sanserif"><strong>$title</strong></font>
 #*          *##if( $summary )
            <br><font face="arial,helvetica,sanserif">$summary</font>
 #*          *##end
          </td>
          <td>
 #*        *##if( $project.logo )
            #set( $alt = $project.logo )
            #set( $home = $project.attribute("href") )
            #set( $src = $project.logo.attribute( "href" ) )
            <!-- PROJECT LOGO -->
            <a href="$home">
              <img src="${relative-path}$src" align="right" alt="$alt" border="0"/>
            </a>
 #*        *##end
          </td>
      </tr></table>
    </td>
  </tr>

  <!-- START RIGHT SIDE MAIN BODY -->
  <tr>
    <td  valign="top" align="left">
 #*    *##if ($node.name().equals("task"))
 #*      Use description from merged XML if available, else javadoc comment *#
 #*      *##if ($node.external.description)
          <!-- Applying task/description -->
 #*        *#$context.applyTemplates("external/description")
 #*      *##else
          <!-- Applying task/long-description -->
 #*        *#$context.applyTemplates("long-description")
 #*      *##end
 #*     *#$context.applyTemplates("structure/attributes")
 #*     *#$context.applyTemplates("structure/elements")
 #*     *#$context.applyTemplates("external/section")
 #*    *##end
    </td>
  </tr>
  <!-- END RIGHT SIDE MAIN BODY -->

      <!-- FOOTER SEPARATOR -->
      <tr>
        <td>
          <hr noshade="" size="1"/>
        </td>
      </tr>

      <!-- PAGE FOOTER -->
      <tr>
        <td>
          <div align="center"><font color="$body-link" size="-1"><em>
            Copyright &#169; 2000-2002, Apache Software Foundation
          </em></font></div>
        </td>
      </tr>
  <!-- FOOTER SEPARATOR -->
  <tr>
    <td>
      <hr noshade="" size="1"/>
    </td>
  </tr>

  <!-- PAGE FOOTER -->
  <tr>
    <td>
      <div align="center"><font color="$body-link" size="-1"><em>
        Copyright &#169; 2000-2002, Apache Software Foundation
      </em></font></div>
    </td>
  </tr>

    </table>
 </table>

    </body>
    </html>
 </body>
 </html>
 #end

 #*
    Macro to format a table heading cell
 *#
 #macro( th $text )
    <td bgcolor="$table-th-bg" valign="top" align="left">
      <font color="#000000" size="-1" face="arial,helvetica,sanserif">
        <b>$text</b></font>
    </td>
        <td bgcolor="$table-th-bg" valign="top" align="left">
          <font color="#000000" size="-1" face="arial,helvetica,sanserif"><b>$text</b></font>
        </td>
 #end

 #*
    Macro to format a table body cell
 *#
 #macro( td $text )
    <td bgcolor="$table-td-bg" valign="top" align="left">
      <font color="#000000" size="-1" face="arial,helvetica,sanserif">
        $text
      </font>
    </td>
        <td bgcolor="$table-td-bg" valign="top" align="left">
          <font color="#000000" size="-1" face="arial,helvetica,sanserif">$text</font>
        </td>
 #end

 #*
    Macro to format a section banner
 *#
 #macro( section $anchor $name )
    <tr><td bgcolor="$banner-bg">
      <font color="$banner-fg" face="arial,helvetica.sanserif">
        <a name="$anchor">
        <strong>$name</strong></a></font>
    </td></tr>
      <tr><td bgcolor="$banner-bg">
        <font color="$banner-fg" face="arial,helvetica.sanserif">
          <a name="$anchor">
          <strong>$name</strong></a></font>
      </td></tr>
 #end

 #*
@@ -168,75 +177,136 @@


 #*
    Match long-description section
    Process javadoc long description section
 *#
 #match( "long-description" )
    <!-- Start Description -->
    <table border="0" cellspacing="0" cellpadding="2" width="100%">
      <tr><td>&nbsp;</td></tr>

  #section($task_name "$task_title Task Description")
 #*      *##section("description" "Description")

      <tr><td><blockquote>
        $node.value()
        $node.value().trim()
      </blockquote></td></tr>

    </table>
    <!-- End Description -->
 #end

 #*
    Match structure/attributes section
    Process external desciption
 *#
 #match( "structure/attributes" )
 #match( "external/description" )
    <!-- Start Description -->
    <table border="0" cellspacing="0" cellpadding="2" width="100%">
      <tr><td>&nbsp;</td></tr>

  #section("attributes" "Parameters")
 #*      *##section("description" "Description")

      <tr><td><blockquote>
        <table>
          <tr>
  #th("Attribute")
  #th("Description")
  #th("Type")
          </tr>
          $context.applyTemplates("*")
        </table>
 #*      *#$context.applyTemplates("*")
      </blockquote></td></tr>

    </table>
    <!-- End Description -->
 #end

 #*
    Match structure/elements section
    Process top level attributes
 *#
 #match( "structure/elements" )
 #match( "structure/attributes" )
    <!-- Start Attributes -->
    <table border="0" cellspacing="0" cellpadding="2" width="100%">
      <tr><td>&nbsp;</td></tr>

  #section("elements" "Parameters as nested elements")
 #*      *##section("attributes" "Parameters")

      <tr><td><blockquote>
        $context.applyTemplates("*")
        <table>
          <tr>
 #*          *##th("Attribute")
 #*          *##th("Description")
 #*          *##th("Type")
          </tr>
 #*        *#$context.applyTemplates("*")
        </table>
      </blockquote></td></tr>

    </table>
    <!-- End Attributes -->
 #end

 #*
    Process a single attribute
 *#
 #match( "attribute" )
    <!-- Attribute -->
    <tr>
  #td($attrib.name)
  #td($node.description)
  #td($attrib.type)
 #*    *##td($attrib.name)
 #*    *##td($node.description)
 #*    *##td($attrib.type)
    </tr>
 #end

 #*
    Process all elements
 *#
 #match( "elements" )
    <!-- Start Elements -->
    <table border="0" cellspacing="0" cellpadding="2" width="100%">
      <tr><td>&nbsp;</td></tr>

 #*      *##section("elements" "Parameters as nested elements")

      <tr><td><blockquote>
 #*      *#$context.applyTemplates("*")
      </blockquote></td></tr>

    </table>
    <!-- End Elements -->
 #end

 #*
    Process a single element
 *#
 #match( "element" )
    <!-- Start Element -->
    <table border="0" cellspacing="0" cellpadding="2" width="100%">
  #subsection($attrib.name $attrib.name)
      <tr><td>&nbsp;</td></tr>
      <tr><td bgcolor="$sub-banner-bg">
        <font color="$sub-banner-fg" face="arial,helvetica.sanserif" size="-1">
          <strong>$attrib.name</strong> ($attrib.type)</font>
      </td></tr>
      <tr><td><blockquote>
        $node.description
        $node.description.toString().trim()
 #*      *#$context.applyTemplates("*")
      </blockquote></td></tr>
    </table>
    <!-- End Element -->
 #end

 #*
    Process attributes within elements
 *#
 #match( "element/attributes" )
    <!-- Start Attributes -->
    <table border="0" cellspacing="0" cellpadding="2" width="100%">
      <tr><td>&nbsp;</td></tr>

      <tr><td>
        <table>
          <tr>
 #*          *##th("Attribute")
 #*          *##th("Description")
 #*          *##th("Type")
          </tr>
 #*        *#$context.applyTemplates("*")
        </table>
      </td></tr>

    </table>
    <!-- End Attributes -->
 #end


--- a/proposal/xdocs/src/org/apache/tools/ant/taskdefs/condition.xml
+++ b/proposal/xdocs/src/org/apache/tools/ant/taskdefs/condition.xml
@@ -0,0 +1,54 @@
 <!-- Condition task -->
 <external>
 <description>

 <p>Sets a property if a certain condition holds true - this is a
 generalization of <a href="available.html">Available</a> and <a
 href="uptodate.html">Uptodate</a>.</p>
 <p>If the condition holds true, the property value is set to true by
 default; otherwise, the property is not set. You can set the value to
 something other than the default by specifying the <code>value</code>
 attribute.</p>
 <p>Conditions are specified as <a href="#nested">nested elements</a>,
 you must specify exactly one condition.</p>

 </description>

 <section anchor="examples" name="Examples">

 <pre>
  &lt;condition property=&quot;javamail.complete&quot;&gt;
    &lt;and&gt;
      &lt;available classname=&quot;javax.activation.DataHandler&quot; /&gt;
      &lt;available classname=&quot;javax.mail.Transport&quot; /&gt;
    &lt;/and&gt;
  &lt;/condition&gt;
 </pre>
 <p>sets the property <code>javamail.complete</code> if both the
 JavaBeans Activation Framework and JavaMail are available in the
 classpath.</p>

 <pre>
  &lt;condition property=&quot;isMacOsButNotMacOsX&quot;&gt;
    &lt;and&gt;
      &lt;os family=&quot;mac&quot; />
      &lt;not&gt;
        &lt;os family=&quot;unix&quot; />
      &lt;/not&gt;
    &lt;/and&gt;
  &lt;/condition&gt;
 </pre>
 <p>sets the property <code>isMacOsButNotMacOsX</code> if the current
 operating system is MacOS, but not MacOS X - which Ant considers to be
 in the Unix family as well.</p>

 <pre>
  &lt;condition property=&quot;isSunOSonSparc&quot;&gt;
    &lt;os name=&quot;SunOS&quot; arch=&quot;sparc&quot; />
  &lt;/condition&gt;
 </pre>
 <p>sets the property <code>isSunOSonSparc</code> if the current
 operating system is SunOS and if it is running on a sparc architecture.</p>

 </section>
 </external>
--- a/proposal/xdocs/src/org/apache/tools/ant/taskdefs/javac.xml
+++ b/proposal/xdocs/src/org/apache/tools/ant/taskdefs/javac.xml
@@ -0,0 +1,195 @@
 <!-- javac task -->
 <external>
 <description>

 <p>Compiles a Java source tree.</p>

 <p>The source and destination directory will be recursively scanned for Java
 source files to compile. Only Java files that have no corresponding class file
 or where the class file is older than the java file will be compiled.</p>

 <p>Note: Ant uses only the names of the source and class files to find
 the classes that need a rebuild. It will not scan the source and therefor
 will have no knowledge about nested classes, classes that are named different
 from the source file and so on.</p>

 <p>The directory structure of the source tree should follow the package
 hierarchy.</p>

 <p>It is possible to refine the set of files that are being compiled/copied.
 This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
 attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
 have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
 the files you want to have excluded. This is also done with patterns. And
 finally with the <i>defaultexcludes</i> attribute, you can specify whether you
 want to use default exclusions or not. See the section on <a
 href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the
 inclusion/exclusion of files works, and how to write patterns.</p>

 <p>It is possible to use different compilers. This can be selected with the
 &quot;build.compiler&quot; property or the compiler attribute. Here are the choices:-</p>
 <ul>
  <li>classic (the standard compiler of JDK 1.1/1.2) - javac1.1 and
     javac1.2 can be used as aliases</li>
  <li>modern (the standard compiler of JDK 1.3/1.4) - javac1.3 and
     javac1.4 can be used as aliases</li>
  <li>jikes (the <a
    href="http://oss.software.ibm.com/developerworks/opensource/jikes/project" target="_top">Jikes</a>
    compiler)</li>
  <li>jvc (the Command-Line Compiler from Microsoft's SDK for Java /
    Visual J++) - microsoft can be used as an alias</li>
  <li>kjc (the <a href="http://www.dms.at/kopi/" target="_top">kopi</a>
    compiler)</li>
  <li>gcj (the gcj compiler from gcc)</li>
  <li>sj (Symantec java compiler) - symantec can be used as an alias</li>
  <li>extJavac (run either modern or classic in a JVM of its own)</li>
 </ul>
 <p>For JDK 1.1/1.2, classic is the default. For JDK 1.3/1.4, modern is the default.
 If you wish to use a different compiler interface than those
 supplied, write a class that implements the CompilerAdapter interface
 (package org.apache.tools.ant.taskdefs.compilers). Supply the full
 classname in the &quot;build.compiler&quot; property.</p>

 <p>The fork attribute overrides the build.compiler setting and expects
 a JDK1.1 or higher to be set in java.home.</p>

 <p>This task will drop all entries that point to non-existent
 files/directories from the CLASSPATH it passes to the compiler.</p>

 <p><strong>Windows Note:</strong>When the modern compiler is used
 in unforked mode on Windows, it locks up the files present in the
 classpath of the &lt;javac&gt; task, and does not release them.  The side
 effect of this is that you will not be able to delete or move
 those files later on in the build.  The workaround is to fork when
 invoking the compiler.</p>

 </description>

 <section anchor="examples" name="Examples">
 <pre>  &lt;javac srcdir=&quot;${src}&quot;
         destdir=&quot;${build}&quot;
         classpath=&quot;xyz.jar&quot;
         debug=&quot;on&quot;
  /&gt;</pre>
 <p>compiles all <code>.java</code> files under the <code>${src}</code>
 directory, and stores
 the <code>.class</code> files in the <code>${build}</code> directory.
 The classpath used contains <code>xyz.jar</code>, and debug information is on.</p>

 <pre>  &lt;javac srcdir=&quot;${src}&quot;
         destdir=&quot;${build}&quot;
         fork=&quot;true&quot;
  /&gt;</pre>
 <p>compiles all <code>.java</code> files under the <code>${src}</code>
 directory, and stores the <code>.class</code> files in the
 <code>${build}</code> directory.  This will fork off the javac
 compiler using the default javac executable.</p>

 <pre>  &lt;javac srcdir=&quot;${src}&quot;
         destdir=&quot;${build}&quot;
         fork=&quot;java$$javac.exe&quot;
  /&gt;</pre>
 <p>compiles all <code>.java</code> files under the <code>${src}</code>
 directory, and stores the <code>.class</code> files in the
 <code>${build}</code> directory.  This will fork off the javac
 compiler using the executable named <code>java$javac.exe</code>.  Note
 that the <code>$</code> sign needs to be escaped by a second one.</p>

 <pre>  &lt;javac srcdir=&quot;${src}&quot;
         destdir=&quot;${build}&quot;
         includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
         excludes=&quot;mypackage/p1/testpackage/**&quot;
         classpath=&quot;xyz.jar&quot;
         debug=&quot;on&quot;
  /&gt;</pre>
 <p>compiles <code>.java</code> files under the <code>${src}</code>
 directory, and stores the
 <code>.class</code> files in the <code>${build}</code> directory.
 The classpath used contains <code>xyz.jar</code>, and debug information is on.
 Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are
 used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded
 from compilation.</p>

 <pre>  &lt;javac srcdir=&quot;${src}:${src2}&quot;
         destdir=&quot;${build}&quot;
         includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
         excludes=&quot;mypackage/p1/testpackage/**&quot;
         classpath=&quot;xyz.jar&quot;
         debug=&quot;on&quot;
  /&gt;</pre>

 <p>is the same as the previous example, with the addition of a second
 source path, defined by
 the property <code>src2</code>. This can also be represented using nested
 <code>&lt;src&gt;</code> elements as follows:</p>

 <pre>  &lt;javac destdir=&quot;${build}&quot;
         classpath=&quot;xyz.jar&quot;
         debug=&quot;on&quot;&gt;
    &lt;src path=&quot;${src}&quot;/&gt;
    &lt;src path=&quot;${src2}&quot;/&gt;
    &lt;include name=&quot;mypackage/p1/**&quot;/&gt;
    &lt;include name=&quot;mypackage/p2/**&quot;/&gt;
    &lt;exclude name=&quot;mypackage/p1/testpackage/**&quot;/&gt;
  &lt;/javac&gt;</pre>

 <p><b>Note:</b> If you are using Ant on Windows and a new DOS window pops up
 for every use of an external compiler, this may be a problem of the JDK you are using.
 This problem may occur with all JDKs &lt; 1.2.</p>

 <p><b>Note:</b> If you wish to compile only source-files located in some packages below a
 common root you should not include these packages in the srcdir-attribute. Use include/exclude-attributes
 or elements to filter for these packages. If you include part of your package-structure inside the srcdir-attribute
 (or nested src-elements) Ant will start to recompile your sources every time you call it.</p>

 </section>

 <section anchor="jikes" name="Jikes Notes">

 <p>Jikes supports some extra options, which can be set be defining
 properties prior to invoking the task. The ant developers are aware that
 this is ugly and inflexible -expect a better solution in the future. All
 the options are boolean, and must be set to &quot;true&quot; or &quot;yes&quot; to be
 interpreted as anything other than false; by default
 build.compiler.warnings is &quot;true&quot; while all others are &quot;false&quot;</p>

 <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top">
 	build.compiler.emacs
 	</td>
 	<td valign="top">
 	Enable emacs compatible error messages
    </td>
  </tr>
  <tr>
    <td valign="top">
 	build.compiler.warnings<br />
        <b>This property has been deprecated, use the nowarn attribute
          instead</b>
 	</td>
 	<td valign="top">
 	don't disable warning messages
    </td>
  </tr>
  <tr>
    <td valign="top">
 	build.compiler.pedantic
 	</td>
 	<td valign="top">
 	enable pedantic warnings
    </td>
  </tr>
  <tr>
    <td valign="top">
 	build.compiler.fulldepend
 	</td>
 	<td valign="top">
 	enable full dependency checking,<br />
 	&quot;+F&quot; in the jikes manual.
    </td>
  </tr>
 </table>

 </section>
 </external>
--- a/proposal/xdocs/src/org/apache/tools/ant/taskdefs/javadoc.xml
+++ b/proposal/xdocs/src/org/apache/tools/ant/taskdefs/javadoc.xml
@@ -0,0 +1,59 @@
 <!-- javadoc task -->
 <external>
 <description>

 <p>Generates code documentation using the javadoc tool.</p>

 <p>The source directory will be recursively scanned for Java source files to process
 but only those matching the inclusion rules, and not matching the exclusions rules
 will be passed to the javadoc tool. This
 allows wildcards to be used to choose between package names, reducing verbosity
 and management costs over time. This task, however, has no notion of
 &quot;changed&quot; files, unlike the <a href="javac.html">javac</a> task. This means
 all packages will be processed each time this task is run. In general, however,
 this task is used much less frequently.</p>

 <p>This task works seamlessly between different javadoc versions (1.1 and 1.2),
 with the obvious restriction that the 1.2 attributes will be ignored if run in a
 1.1 VM.</p>

 <p>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the
 same VM as ant without breaking functionality. For this reason, this task
 always forks the VM. This overhead is not significant since javadoc is normally a heavy
 application and will be called infrequently.</p>

 <p>NOTE: the packagelist attribute allows you to specify the list of packages to
 document outside of the Ant file. It's a much better practice to include everything
 inside the build.xml file. This option was added in order to make it easier to
 migrate from regular makefiles, where you would use this option of javadoc.
 The packages listed in packagelist are not checked, so the task performs even
 if some packages are missing or broken. Use this option if you wish to convert from
 an existing makefile. Once things are running you should then switch to the regular
 notation. </p>

 <p><i><b>DEPRECATION:</b> the javadoc2 task simply points to the javadoc task and it's
 there for back compatibility reasons. Since this task will be removed in future
 versions, you are strongly encouraged to use <a href="javadoc.html">javadoc</a>
 instead.</i></p>
 </description>

 <section anchor="examples" name="Example">
 <pre>  &lt;javadoc packagenames=&quot;com.dummy.test.*&quot;
           sourcepath=&quot;src&quot;
           excludepackagenames=&quot;com.dummy.test.doc-files.*&quot;
           defaultexcludes=&quot;yes&quot;
           destdir=&quot;docs/api&quot;
           author=&quot;true&quot;
           version=&quot;true&quot;
           use=&quot;true&quot;
           windowtitle=&quot;Test API&quot;&gt;
    &lt;doctitle&gt;&lt;![CDATA[&lt;h1&gt;Test&lt;/h1&gt;]]&gt;&lt;/doctitle&gt;
    &lt;bottom&gt;&lt;![CDATA[&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;]]&gt;&lt;/bottom&gt;
    &lt;tag name=&quot;todo&quot; scope=&quot;all&quot; description=&quot;To do:&quot; /&gt;
    &lt;group title=&quot;Group 1 Packages&quot; packages=&quot;com.dummy.test.a*&quot;/&gt;
    &lt;group title=&quot;Group 2 Packages&quot; packages=&quot;com.dummy.test.b*:com.dummy.test.c*&quot;/&gt;
    &lt;link offline=&quot;true&quot; href=&quot;http://java.sun.com/products/jdk/1.2/docs/api/&quot; packagelistLoc=&quot;C:\tmp&quot;/&gt;
    &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
  &lt;/javadoc&gt;</pre>
 </section>
 </external>
--- a/proposal/xdocs/src/org/apache/tools/ant/taskdefs/tar.xml
+++ b/proposal/xdocs/src/org/apache/tools/ant/taskdefs/tar.xml
@@ -0,0 +1,111 @@
 <!-- tar task -->
 <external>
 <description>
 <p>Creates a tar archive.</p>

 <p>The <i>basedir</i> attribute is the reference directory from where to tar.</p>

 <p>This task is a <a href="../dirtasks.html#directorybasedtasks">directory based task</a>
 and, as such, forms an implicit <a href="../CoreTypes/fileset.html">Fileset</a>. This
 defines which files, relative to the <i>basedir</i>, will be included in the
 archive. The tar task supports all the attributes of Fileset to refine the
 set of files to be included in the implicit fileset.</p>

 <p>In addition to the implicit fileset, the tar task supports nested filesets. These
 filesets are extended to allow control over the access mode, username and groupname
 to be applied to the tar entries. This is useful, for example, when preparing archives for
 Unix systems where some files need to have execute permission.</p>

 <p>Early versions of tar did not support path lengths greater than 100
 characters. Modern versions of tar do so, but in incompatible ways.
 The behaviour of the tar task when it encounters such paths is
 controlled by the <i>longfile</i> attribute.
 If the longfile attribute is set to <code>fail</code>, any long paths will
 cause the tar task to fail.  If the longfile attribute is set to
 <code>truncate</code>, any long paths will be truncated to the 100 character
 maximum length prior to adding to the archive. If the value of the longfile
 attribute is set to <code>omit</code> then files containing long paths will be
 omitted from the archive.  Either option ensures that the archive can be
 untarred by any compliant version of tar. If the loss of path or file
 information is not acceptable, and it rarely is, longfile may be set to the
 value <code>gnu</code>. The tar task will then produce a GNU tar file which
 can have arbitrary length paths. Note however, that the resulting archive will
 only be able to be untarred with GNU tar.  The default for the longfile
 attribute is <code>warn</code> which behaves just like the gnu option except
 that it produces a warning for each file path encountered that does not match
 the limit.</p>

 <p>Note that this task does not perform compression. You might want to use the
 <a href="gzip.html">GZip</a> task to prepare a .tar.gz package.</p>
 </description>

 <section anchor="examples" name="Examples">
 <pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot; basedir=&quot;htdocs/manual&quot;/&gt;
  &lt;gzip zipfile=&quot;${dist}/manual.tar.gz&quot; src=&quot;${dist}/manual.tar&quot;/&gt;</pre>
 <p>tars all files in the <code>htdocs/manual</code> directory into a file called <code>manual.tar</code>
 in the <code>${dist}</code>  directory, then applies the gzip task to compress
 it.</p>
 <pre>  &lt;tar destfile=&quot;${dist}/manual.tar&quot;
       basedir=&quot;htdocs/manual&quot;
       excludes=&quot;mydocs/**, **/todo.html&quot;
  /&gt;</pre>
 <p>tars all files in the <code>htdocs/manual</code> directory into a file called <code>manual.tar</code>
 in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
 or files with the name <code>todo.html</code> are excluded.</p>

 <pre>
 &lt;tar destfile=&quot;${basedir}/docs.tar&quot;&gt;
  &lt;tarfileset dir=&quot;${dir.src}/docs&quot;
              fullpath=&quot;/usr/doc/ant/README&quot;
              preserveLeadingSlashes=&quot;true&quot;&gt;
    &lt;include name=&quot;readme.txt&quot;/&gt;
  &lt;/tarfileset&gt;
  &lt;tarfileset dir=&quot;${dir.src}/docs&quot;
              prefix=&quot;/usr/doc/ant&quot;
              preserveLeadingSlashes=&quot;true&quot;&gt;
    &lt;include name=&quot;*.html&quot;/&gt;
  &lt;/tarfileset&gt;
 &lt;/tar&gt;</pre>

 <p>
  Writes the file <code>docs/readme.txt</code> as
  <code>/usr/doc/ant/README</code> into the archive. All
  <code>*.html</code> files in the <code>docs</code> directory are
  prefixed by <code>/usr/doc/ant</code>, so for example
  <code>docs/index.html</code> is written as
  <code>/usr/doc/ant/index.html</code> to the archive.
 </p>


 <pre>&lt;tar longfile=&quot;gnu&quot;
     destfile=&quot;${dist.base}/${dist.name}-src.tar&quot; &gt;
  &lt;tarfileset dir=&quot;${dist.name}/..&quot; mode=&quot;755&quot; username=&quot;ant&quot; group=&quot;ant&quot;&gt;
    &lt;include name=&quot;${dist.name}/bootstrap.sh&quot;/&gt;
    &lt;include name=&quot;${dist.name}/build.sh&quot;/&gt;
  &lt;/tarfileset&gt;
  &lt;tarfileset dir=&quot;${dist.name}/..&quot; username=&quot;ant&quot; group=&quot;ant&quot;&gt;
    &lt;include name=&quot;${dist.name}/**&quot;/&gt;
    &lt;exclude name=&quot;${dist.name}/bootstrap.sh&quot;/&gt;
    &lt;exclude name=&quot;${dist.name}/build.sh&quot;/&gt;
  &lt;/tarfileset&gt;
 &lt;/tar&gt; </pre>

 <p>This example shows building a tar which uses the GNU extensions for long paths and
 where some files need to be marked as executable (mode 755)
 and the rest are use the default mode (read-write by owner). The first
 fileset selects just the executable files. The second fileset must exclude
 the executable files and include all others. </p>

 <p><strong>Note: </strong> The tar task does not ensure that a file is only selected
 by one fileset. If the same file is selected by more than one fileset, it will be included in the
 tar file twice, with the same path.</p>

 <p><strong>Note:</strong> The patterns in the include and exclude
 elements are considered to be relative to the corresponding dir
 attribute as with all other filesets.  In the example above,
 <code>${dist.name}</code> is not an absolute path, but a simple name
 of a directory, so <code>${dist.name}</code> is a valid path relative
 to <code>${dist.name}/..</code>.</p>

 </section>
 </external>
--- a/proposal/xdocs/src/org/apache/tools/ant/xdoclet/AntTagsHandler.java
+++ b/proposal/xdocs/src/org/apache/tools/ant/xdoclet/AntTagsHandler.java
@@ -55,6 +55,9 @@ package org.apache.tools.ant.xdoclet;

 import com.sun.javadoc.ClassDoc;
 import com.sun.javadoc.MethodDoc;
 import com.sun.javadoc.Parameter;
 import com.sun.javadoc.Type;

 import xdoclet.XDocletException;
 import xdoclet.XDocletTagSupport;
 import xdoclet.tags.AbstractProgramElementTagsHandler;
@@ -122,6 +125,25 @@ public class AntTagsHandler extends XDocletTagSupport {
        }
    }

    /**
     * Determines if there's at least one Ant attribute.
     *
     *@param  template              XDoclet template
     *@param  attributes            Tag parameters
     *@exception  XDocletException  Oops!
     */
    public void ifHasAttributes(String template, Properties attributes) throws XDocletException {
        // throw exception if not an Ant task

        ClassDoc cur_class = getCurrentClass();

        MethodDoc[] methods = getAttributeMethods(cur_class);

        if (methods.length > 0) {
            generate(template);
        }
    }

    /**
     *  Iterates over all Ant nested element methods (addXXX, addConfiguredXXX, addXXX)
     *
@@ -161,11 +183,43 @@ public class AntTagsHandler extends XDocletTagSupport {
        return elementName.toLowerCase();
    }

    /**
     * Provides the element type for the current method
     */
    public String elementType() throws XDocletException {
        ClassDoc classDoc = elementClassDoc();
        if (classDoc == null) {
            throw new XDocletException("Method is not an Ant element!");
        }
        return classDoc.qualifiedName();
    }

    /**
     * Provides the element type for the current method.  If the return type
     * is null, the first parameter is used.
     */
    private ClassDoc elementClassDoc() throws XDocletException {
        ClassDoc classDoc = null;
        String methodName = getCurrentMethod().name();
        if (methodName.startsWith("addConfigured") ||
            methodName.startsWith("add") ||
            methodName.startsWith("create"))
        {
            classDoc = getCurrentMethod().returnType().asClassDoc();
            if (classDoc == null) {
                Parameter[] params = getCurrentMethod().parameters();
                if (params.length == 1) {
                    classDoc = params[0].type().asClassDoc();
                }
            }
        }
        return classDoc;
    }

    /**
     * Provides the Ant task name.
     *
     * @see getTaskName
     * @see #getTaskName(ClassDoc)
 	 * @doc:tag      type="content"
     */
    public String taskName() throws XDocletException {
@@ -204,7 +258,7 @@ public class AntTagsHandler extends XDocletTagSupport {
    /**
     * Provides the Ant category name.
     *
     * @see getCategoryName
     * @see #getCategoryName(ClassDoc)
     */
    public String categoryName() throws XDocletException {
        return getCategoryName(getCurrentClass());
@@ -273,6 +327,12 @@ public class AntTagsHandler extends XDocletTagSupport {
                continue;
            }

            // ensure method only has one parameter
            Parameter[] params = methods[i].parameters();
            if (params.length != 1) {
                continue;
            }

            attributeMethods.add(methods[i]);
        }

@@ -291,6 +351,18 @@ public class AntTagsHandler extends XDocletTagSupport {
        for (int i = 0; i < methods.length; i++) {
            String name = methods[i].name();

            // ensure if there are no parameters, there is a return type,
            // otherwise ensure there's only one parameter.
            Parameter[] params = methods[i].parameters();
            if (params.length == 0) {
                if (methods[i].returnType().asClassDoc() == null) {
                    continue;
                }
            }
            else if (params.length != 1) {
                continue;
            }

            if ((name.startsWith("add") && !name.equals("addTask")) ||
                    name.startsWith("create")) {
                attributeMethods.add(methods[i]);
--- a/proposal/xdocs/templates/task_xdoc.template
+++ b/proposal/xdocs/templates/task_xdoc.template
@@ -1,8 +1,9 @@
 <XDtTagDef:tagDef namespace="Ant" handler="org.apache.tools.ant.xdoclet.AntTagsHandler"/>

 <task name="<XDtAnt:taskName/>" category="<XDtAnt:categoryName/>"
      classname="<XDtClass:fullClassName/>">

  <XDtMerge:merge file="{0}.xml" generateMergedFile="false"></XDtMerge:merge>

  <short-description><![CDATA[<XDtClass:firstSentenceDescription/>]]></short-description>
  <long-description>
    <![CDATA[<XDtClass:classComment no-comment-signs="true"/>]]>
@@ -11,23 +12,37 @@
  <structure>

    <attributes>
      <XDtAnt:forAllAttributes>
        <attribute name="<XDtMethod:propertyName/>" type="<XDtParameter:forAllMethodParams><XDtParameter:methodParamType/></XDtParameter:forAllMethodParams>">
          <description><![CDATA[
            <XDtMethod:methodComment no-comment-signs="true"/>
          ]]></description>
        </attribute>
      </XDtAnt:forAllAttributes>
    <XDtAnt:forAllAttributes>
      <attribute name="<XDtMethod:propertyName/>" type="<XDtParameter:forAllMethodParams><XDtParameter:methodParamType/></XDtParameter:forAllMethodParams>">
        <description><![CDATA[
          <XDtMethod:methodComment no-comment-signs="true"/>
        ]]></description>
      </attribute>
    </XDtAnt:forAllAttributes>
    </attributes>

    <elements>
      <XDtAnt:forAllElements>
        <element name="<XDtAnt:elementName/>">
          <description><![CDATA[
            <XDtMethod:methodComment no-comment-signs="true"/>
          ]]></description>
        </element>
      </XDtAnt:forAllElements>
    <XDtAnt:forAllElements>
      <element name="<XDtAnt:elementName/>" type="<XDtAnt:elementType/>">
        <description>
          <![CDATA[<XDtMethod:methodComment no-comment-signs="true"/>]]>
        </description>
        <XDtClass:pushClass value="<XDtAnt:elementType/>">
        <XDtAnt:ifHasAttributes>
        <attributes>
          <XDtAnt:forAllAttributes>
          <attribute name="<XDtMethod:propertyName/>" type="<XDtParameter:forAllMethodParams><XDtParameter:methodParamType/></XDtParameter:forAllMethodParams>">
            <description><![CDATA[
              <XDtMethod:methodComment no-comment-signs="true"/>
            ]]></description>
          </attribute>
          </XDtAnt:forAllAttributes>
        </attributes>
        </XDtAnt:ifHasAttributes>
        </XDtClass:pushClass>
      </element>

    </XDtAnt:forAllElements>
    </elements>

    <!-- @todo: wrap setCurrentMethod inside AntTagsHandler -->
@@ -41,7 +56,6 @@

  </structure>

    <!-- merge point for samples? -->
 </task>