From 63d1abc7c081429ad0083ae30d418f44977accf1 Mon Sep 17 00:00:00 2001 From: Gintas Grigelionis Date: Sat, 3 Mar 2018 21:26:50 +0100 Subject: [PATCH] Style corrections, in particular regarding footnotes --- manual/Tasks/copy.html | 2 +- manual/Tasks/filter.html | 19 +- manual/Tasks/java.html | 4 +- manual/Tasks/jjtree.html | 18 +- manual/Tasks/rmic.html | 4 +- manual/Types/resources.html | 10 +- manual/develop.html | 501 +++++++++++++++--------------------- 7 files changed, 241 insertions(+), 317 deletions(-) diff --git a/manual/Tasks/copy.html b/manual/Tasks/copy.html index 69219f3b0..9c2cc9018 100644 --- a/manual/Tasks/copy.html +++ b/manual/Tasks/copy.html @@ -72,7 +72,7 @@ note.

todir - The directory to copy to. + The directory to copy to. overwrite diff --git a/manual/Tasks/filter.html b/manual/Tasks/filter.html index 09c263b8e..3525756aa 100644 --- a/manual/Tasks/filter.html +++ b/manual/Tasks/filter.html @@ -30,9 +30,8 @@ these as filters. Token filters are used by all tasks that perform file copying operations through the Project commodity methods. See the warning here before using.

-

Note 1: the token string must not contain the separators chars (@).
Note 2: -Either token and value attributes must be provided, or only -the filtersfile attribute.

+

The task uses @ as token separator. Token strings cannot contain separator characters; +incorrect tokens are ignored.

Parameters

@@ -43,22 +42,20 @@ the filtersfile attribute.

- - + + - - + - - +
tokenthe token string without @Yes*the token string without the separator chars (@)Yes; either both token and value, or + only filtersfile
valuethe string that should be put to replace the token when the file is copiedYes*the string that should be put to replace the token when the file is copied
filtersfileThe file from which the filters must be read. This file must be a formatted as a property - file.Yes*The file from which the filters must be read. This file must be a formatted as + a property file.
-

* see Note 1 and 2 above parameters table.

Examples

 <filter token="year" value="2000"/>
diff --git a/manual/Tasks/java.html b/manual/Tasks/java.html
index 3883b6d16..01b3759e4 100644
--- a/manual/Tasks/java.html
+++ b/manual/Tasks/java.html
@@ -56,7 +56,7 @@ because it tries to read from the standard input.

     jar
     the location of the jar file to execute (must have a Main-Class
       entry in the manifest). fork must be set to true if this option is selected.
-      See notes below for more details.
+      See notes below for more details.
     
   
   
@@ -302,7 +302,7 @@ structure and can also be set via a nested modulepath element.<
 
The location of modules that replace upgradeable modules in the runtime image can be specified
 using this path-like structure.

 
-
JAR file execution

+
JAR file execution

 
 
The parameter of the jar attribute is of type File; that is, the
 parameter is resolved to an absolute file relative to the base directory of the
diff --git a/manual/Tasks/jjtree.html b/manual/Tasks/jjtree.html
index 0757856a1..0c6fc93f0 100644
--- a/manual/Tasks/jjtree.html
+++ b/manual/Tasks/jjtree.html
@@ -418,13 +418,13 @@ versions
   Not Supported
   Same
 
-
+
   
jjtree -OUTPUT_FILE:D:/tmp/subdir/output.jj grammar.jjt
     /tmp/subdir/output.jj
     /tmp/<generated>.java

   
   Not Supported
-  Not Supported *)
+  Not Supported*
 
 
   
jjtree -OUTPUT_FILE:D:/tmp/subdir/output.jj relative/grammar.jjt
@@ -432,7 +432,7 @@ versions
     /tmp/<generated>.java

   
   Not Supported
-  Not Supported *)
+  Not Supported*
 
 
   
jjtree -OUTPUT_FILE:D:/tmp/subdir/output.jj /tmp/absolute/grammar.jjt
@@ -440,7 +440,7 @@ versions
     /tmp/<generated>.java

   
   Not Supported
-  Not Supported *)
+  Not Supported*
 
 
   
jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative grammar.jjt
@@ -493,11 +493,11 @@ versions
   
 
 
-
*) Footnote: When running JJTree with the Ant taskdef jjtree the
-option -OUTPUT_DIRECTORY must always be set, because the project's basedir
-and the Ant working directory might differ. So even if you don't specify
-the outputdirectory for taskdef jjtree, JJTree will be called with
-the -OUTPUT_DIRECTORY set to the project's basedir.  But when
+
Note: When running JJTree with
+the Ant taskdef jjtree the option -OUTPUT_DIRECTORY must always be set,
+because the project's basedir and the Ant working directory might differ. So even if you
+don't specify the outputdirectory for taskdef jjtree, JJTree will be called
+with the -OUTPUT_DIRECTORY set to the project's basedir.  But when
 the -OUTPUT_DIRECTORY is set, the -OUTPUT_FILE setting is handled as if
 relative to this -OUTPUT_DIRECTORY. Thus when the -OUTPUT_FILE is absolute
 or contains a drive letter we have a problem.  Therefore absolute outputfiles (when
diff --git a/manual/Tasks/rmic.html b/manual/Tasks/rmic.html
index 5af1a7ee3..86992f4ef 100644
--- a/manual/Tasks/rmic.html
+++ b/manual/Tasks/rmic.html
@@ -77,7 +77,7 @@ documentation to learn how to use it.

     Description
     Required
   
-  
+  
     base
     the location to store the compiled files.  Also serves as the parent directory for any
       non-Fileset includes, etc.  (This functionality has remained unchanged.)
@@ -214,7 +214,7 @@ documentation to learn how to use it.

   
 
 
-
Note:

+
Note:

 
    
   
  • Maintaining compatibility, base, when specified by itself, serves as both the
     parent directory for any source files AND the output directory.
    • 
diff --git a/manual/Types/resources.html b/manual/Types/resources.html
index f27524d15..f8dfda866 100644
--- a/manual/Types/resources.html
+++ b/manual/Types/resources.html
@@ -503,17 +503,17 @@ selection.
     Whether patterns are case-sensitive
     No; default true
   
-  
+  
     followsymlinks
     Whether to follow symbolic links (see note below)
     No; default true
   
 
 
-
+
 
 
    restrict
    
 
    Restricts a nested resource collection using resource selectors:
    
diff --git a/manual/develop.html b/manual/develop.html
index 01f3d7f32..424e54ce5 100644
--- a/manual/develop.html
+++ b/manual/develop.html
@@ -29,207 +29,164 @@
 
    It is very easy to write your own task:
    
 
      
   
    1. Create a Java class that extends org.apache.tools.ant.Task
-      or another class that was designed to be extended.
      2. 
-
-  
    2. For each attribute, write a setter method. The setter method must be a
-    public void method that takes a single argument. The
-    name of the method must begin with set, followed by the
-    attribute name, with the first character of the name in uppercase, and the rest in
-    lowercase*.  That is, to support an attribute named
-    file you create a method setFile.
-    Depending on the type of the argument, Ant will perform some
-    conversions for you, see below.
      3. 
-
-  
    3. If your task shall contain other tasks as nested elements (like
-    parallel), your
-    class must implement the interface
-    org.apache.tools.ant.TaskContainer.  If you do so, your
-    task can not support any other nested elements.  See
-    below.
      4. 
-
-  
    4. If the task should support character data (text nested between the
-    start and end tags), write a public void addText(String)
-    method.  Note that Ant does not expand properties on
-    the text it passes to the task.
      5. 
-
-  
    5. For each nested element, write a create, add or
-    addConfigured method.  A create method must be a
-    public method that takes no arguments and returns an
-    Object type. The name of the create method must begin
-    with create, followed by the element name. An add (or
-    addConfigured) method must be a public void method that
-    takes a single argument of an Object type with a
-    no-argument constructor.  The name of the add (addConfigured) method
-    must begin with add (addConfigured),
-    followed by the element name.  For a more complete discussion see
-    below.
      6. 
-
-  
    6. Write a public void execute method, with no arguments, that
-    throws a BuildException. This method implements the task
-    itself.
      7. 
+    or another class that was designed to be extended.
+
+  
    7. For each attribute, write a setter method. The setter method
+    must be a public void method that takes a single argument. The name of the method
+    must begin with set, followed by the attribute name, with the first character of
+    the name in uppercase, and the rest in lowercase*.  That
+    is, to support an attribute named file you create a method setFile.
+    Depending on the type of the argument, Ant will perform some conversions for you,
+    see below.
      8. 
+
+  
    8. If your task shall contain other tasks as nested elements
+    (like parallel), your class must implement the
+    interface org.apache.tools.ant.TaskContainer.  If you do so, your task can not
+    support any other nested elements.  See below.
      9. 
+
+  
    9. If the task should support character data (text nested between the start and end tags), write
+    a public void addText(String) method.  Note that Ant does not
+    expand properties on the text it passes to the task.
      10. 
+
+  
    10. For each nested element, write a create, add or addConfigured
+  method.  A create method must be a public method that takes no arguments and returns
+  an Object type. The name of the create method must begin with create,
+  followed by the element name. An add (or addConfigured) method must be a public void
+  method that takes a single argument of an Object type with a no-argument constructor.
+  The name of the add (addConfigured) method must begin with add
+  (addConfigured), followed by the element name.  For a more complete discussion
+  see below.
      11. 
+
+  
    11. Write a public void execute method, with no arguments, that throws
+    a BuildException. This method implements the task itself.
      12. 
 
    
 
 
    
-
    * Actually the case of the letters after
-the first one doesn't really matter to Ant, using all lower case is a
-good convention, though.
    
+
    * Actually the case of the letters after the first
+one doesn't really matter to Ant, using all lower case is a good convention, though.
    
 
 
    The Life-cycle of a Task
    
 
      
-  
    1. 
-    The xml element that contains the tag corresponding to the
-      task gets converted to an UnknownElement at parse time.
-      This UnknownElement gets placed in a list within a target
-    object, or recursively within another UnknownElement.
+  
    2. The xml element that contains the tag corresponding to the task gets converted to
+    an UnknownElement at parse time.  This UnknownElement gets placed in a
+    list within a target object, or recursively within another UnknownElement.
   
      3. 
-  
    3. 
-      When the target is executed, each UnknownElement is invoked
-    using an perform() method. This instantiates
-    the task. This means that tasks only gets
+
+  
    4. When the target is executed, each UnknownElement is invoked using
+    an perform() method. This instantiates the task. This means that tasks only gets
     instantiated at run time.
   
      5. 
 
-  
    5. The task gets references to its project and location inside the
-    buildfile via its inherited project and
-    location variables.
      6. 
+  
    6. The task gets references to its project and location inside the buildfile via its
+    inherited project and location variables.
      7. 
 
-  
    7. If the user specified an id attribute to this task,
-    the project registers a reference to this newly created task, at run
-    time.
      8. 
+  
    8. If the user specified an id attribute to this task, the project registers a
+    reference to this newly created task, at run time.
      9. 
 
-  
    9. The task gets a reference to the target it belongs to via its
-    inherited target variable.
      10. 
+  
    10. The task gets a reference to the target it belongs to via its inherited target
+    variable.
      11. 
 
   
    11. init() is called at run time.
      12. 
 
-  
    12. All child elements of the XML element corresponding to this task
-    are created via this task's createXXX() methods or
-    instantiated and added to this task via its addXXX()
-    methods, at run time.  Child elements corresponding
-    to addConfiguredXXX() are created at this point but
-    the actual addConfigured method is not called.
      13. 
+  
    13. All child elements of the XML element corresponding to this task are created via this
+    task's createXXX() methods or instantiated and added to this task via
+    its addXXX() methods, at run time.  Child elements corresponding
+    to addConfiguredXXX() are created at this point but the
+    actual addConfigured method is not called.
      14. 
 
-  
    14. All attributes of this task get set via their corresponding
-    setXXX methods, at runtime.
      15. 
+  
    15. All attributes of this task get set via their corresponding setXXX methods, at
+    runtime.
      16. 
 
-  
    16. The content character data sections inside the XML element
-    corresponding to this task is added to the task via its
-    addText method, at runtime.
      17. 
+  
    17. The content character data sections inside the XML element corresponding to this task is added
+    to the task via its addText method, at runtime.
      18. 
 
-  
    18. All attributes of all child elements get set via their corresponding
-    setXXX methods, at runtime.
      19. 
+  
    19. All attributes of all child elements get set via their corresponding setXXX
+    methods, at runtime.
      20. 
 
-  
    20. If child elements of the XML element corresponding to this task
-    have been created for addConfiguredXXX() methods,
-    those methods get invoked now.
      21. 
+  
    21. If child elements of the XML element corresponding to this task have been created
+    for addConfiguredXXX() methods, those methods get invoked now.
      22. 
 
-  
    22. execute() is called at runtime.
-    If target1 and target2 both depend
-    on target3, then running
-    'ant target1 target2' will run all tasks in
-    target3 twice.
      23. 
+  
    23. execute() is called at runtime.  If target1
+    and target2 both depend on target3, then running 'ant target1
+    target2' will run all tasks in target3 twice.
      24. 
 
    
 
 
    Conversions Ant will perform for attributes
    
 
-
    Ant will always expand properties before it passes the value of an
-attribute to the corresponding setter method. Since Ant 1.8, it is
-possible to extend Ant's property handling
-such that a non-string Object may be the result of the evaluation of a string
-containing a single property reference. These will be assigned directly via
-setter methods of matching type. Since it requires some beyond-the-basics
-intervention to enable this behavior, it may be a good idea to flag attributes
-intended to permit this usage paradigm.
-
    
-
-
    The most common way to write an attribute setter is to use a
-java.lang.String argument.  In this case Ant will pass
-the literal value (after property expansion) to your task.  But there
-is more!  If the argument of you setter method is
    
-
-
      
-
-  
    • boolean, your method will be passed the value
-  true if the value specified in the build file is one of
-  true, yes, or on and
-  false otherwise.
      • 
-
-  
    • char or java.lang.Character, your
-  method will be passed the first character of the value specified in
-  the build file.
      • 
-
-  
    • any other primitive type (int, short
-  and so on), Ant will convert the value of the attribute into this
-  type, thus making sure that you'll never receive input that is not a
-  number for that attribute.
      • 
-
-  
    • java.io.File, Ant will first determine whether the
-  value given in the build file represents an absolute path name.  If
-  not, Ant will interpret the value as a path name relative to the
-  project's basedir.
      • 
-
-  
    • org.apache.tools.ant.types.Resource, Ant will
-  resolve the string as a java.io.File as above, then
-  pass in as a org.apache.tools.ant.types.resources.FileResource.
-  Since Ant 1.8
-  
      • 
+
      Ant will always expand properties before it passes the value of an attribute to the corresponding
+setter method. Since Ant 1.8, it is possible to extend
+Ant's property handling such that a non-string Object may be the result of the evaluation of a
+string containing a single property reference. These will be assigned directly via setter methods of
+matching type. Since it requires some beyond-the-basics intervention to enable this behavior, it may
+be a good idea to flag attributes intended to permit this usage paradigm.
      
 
-  
    • org.apache.tools.ant.types.Path, Ant will tokenize
-  the value specified in the build file, accepting : and
-  ; as path separators.  Relative path names will be
-  interpreted as relative to the project's basedir.
      • 
-
-  
    • java.lang.Class, Ant will interpret the value
-  given in the build file as a Java class name and load the named
-  class from the system class loader.
      • 
-
-  
    • any other type that has a constructor with a single
-  String argument, Ant will use this constructor to
-  create a new instance from the value given in the build file.
      • 
-
-  
    • A subclass of
-  org.apache.tools.ant.types.EnumeratedAttribute, Ant
-  will invoke this classes setValue method.  Use this if
-  your task should support enumerated attributes (attributes with
-  values that must be part of a predefined set of values).  See
-  org/apache/tools/ant/taskdefs/FixCRLF.java and the
-  inner AddAsisRemove class used in setCr
-  for an example.
      • 
-
-  
    • A (Java 5) enumeration, Ant will call the setter with the enum constant
-  matching the value given in the build file. This is easier than using
-  EnumeratedAttribute and can result in cleaner code, but of course
-  your task will not run on JDK 1.4 or earlier. Note that any override of
-  toString() in the enumeration is ignored; the build file must use
-  the declared name (see Enum.getName()). You may wish to use lowercase
-  enum constant names, in contrast to usual Java style, to look better in build files.
-  Since Ant 1.7.0
      • 
+
      The most common way to write an attribute setter is to use a java.lang.String
+argument.  In this case Ant will pass the literal value (after property expansion) to your task.
+But there is more!  If the argument of you setter method is
      
 
+
        
+  
      • boolean, your method will be passed the value true if the value
+    specified in the build file is one of true, yes, or on
+    and false otherwise.
        • 
+
+  
      • char or java.lang.Character, your method will be passed the first
+    character of the value specified in the build file.
        • 
+
+  
      • any other primitive type (int, short and so on), Ant will convert
+    the value of the attribute into this type, thus making sure that you'll never receive input that
+    is not a number for that attribute.
        • 
+
+  
      • java.io.File, Ant will first determine whether the value given in the build file
+    represents an absolute path name.  If not, Ant will interpret the value as a path name relative
+    to the project's basedir.
        • 
+
+  
      • org.apache.tools.ant.types.Resource, Ant will resolve the string as
+    a java.io.File as above, then pass in as
+    a org.apache.tools.ant.types.resources.FileResource.  Since Ant 1.8
        • 
+
+  
      • org.apache.tools.ant.types.Path, Ant will tokenize the value specified in the
+    build file, accepting : and ; as path separators.  Relative path names will be
+    interpreted as relative to the project's basedir.
        • 
+
+  
      • java.lang.Class, Ant will interpret the value given in the build file as a Java
+    class name and load the named class from the system class loader.
        • 
+
+  
      • any other type that has a constructor with a single String argument, Ant will use
+    this constructor to create a new instance from the value given in the build file.
        • 
+
+  
      • A subclass of org.apache.tools.ant.types.EnumeratedAttribute, Ant will invoke
+    this classes setValue method.  Use this if your task should support enumerated
+    attributes (attributes with values that must be part of a predefined set of values).
+    See org/apache/tools/ant/taskdefs/FixCRLF.java and the
+    inner AddAsisRemove class used in setCr for an example.
        • 
+
+  
      • A (Java 5) enumeration, Ant will call the setter with the enum constant matching the value
+    given in the build file. This is easier than using EnumeratedAttribute and can
+    result in cleaner code, but of course your task will not run on JDK 1.4 or earlier. Note that
+    any override of toString() in the enumeration is ignored; the build file must use
+    the declared name (see Enum.getName()). You may wish to use lowercase enum constant
+    names, in contrast to usual Java style, to look better in build files.  Since Ant
+    1.7.0
        • 
 
      
 
-
      What happens if more than one setter method is present for a given
-attribute?  A method taking a String argument will always
-lose against the more specific methods.  If there are still more
-setters Ant could chose from, only one of them will be called, but we
-don't know which, this depends on the implementation of your Java
-virtual machine.
      
+
      What happens if more than one setter method is present for a given attribute?  A method taking
+a String argument will always lose against the more specific methods.  If there are
+still more setters Ant could chose from, only one of them will be called, but we don't know which,
+this depends on the implementation of your Java virtual machine.
      
 
 
      Supporting nested elements
      
 
-
      Let's assume your task shall support nested elements with the name
-inner.  First of all, you need a class that represents
-this nested element.  Often you simply want to use one of Ant's
-classes like org.apache.tools.ant.types.FileSet to
-support nested fileset elements.
      
+
      Let's assume your task shall support nested elements with the name inner.  First of
+all, you need a class that represents this nested element.  Often you simply want to use one of
+Ant's classes like org.apache.tools.ant.types.FileSet to support
+nested fileset elements.
      
 
-
      Attributes of the nested elements or nested child elements of them
-will be handled using the same mechanism used for tasks (i.e. setter
-methods for attributes, addText for nested text and
+
      Attributes of the nested elements or nested child elements of them will be handled using the same
+mechanism used for tasks (i.e. setter methods for attributes, addText for nested text and
 create/add/addConfigured methods for child elements).
      
 
-
      Now you have a class NestedElement that is supposed to
-be used for your nested <inner> elements, you have
-three options:
      
+
      Now you have a class NestedElement that is supposed to be used for your
+nested <inner> elements, you have three options:
      
 
 
        
   
      1. public NestedElement createInner()
        2. 
@@ -239,41 +196,32 @@ three options:
        
 
 
        What is the difference?
        
 
-
        Option 1 makes the task create the instance of
-NestedElement, there are no restrictions on the type.
-For the options 2 and 3, Ant has to create an instance of
-NestedInner before it can pass it to the task, this
-means, NestedInner must have a public no-arg
-  constructor or a public one-arg constructor
-    taking a Project class as a parameter.
-This is the only difference between options 1 and 2.
        
-
-
        The difference between 2 and 3 is what Ant has done to the object
-before it passes it to the method.  addInner will receive
-an object directly after the constructor has been called, while
-addConfiguredInner gets the object after the
-attributes and nested children for this new object have been
-handled.
        
-
-
        What happens if you use more than one of the options?  Only one of
-the methods will be called, but we don't know which, this depends on
-the implementation of your JVM.
        
+
        Option 1 makes the task create the instance of NestedElement, there are no
+restrictions on the type.  For the options 2 and 3, Ant has to create an instance
+of NestedInner before it can pass it to the task, this means, NestedInner
+must have a public no-arg constructor or a public one-arg constructor
+taking a Project class as a parameter.  This is the only difference between options 1
+and 2.
        
+
+
        The difference between 2 and 3 is what Ant has done to the object before it passes it to the
+method.  addInner will receive an object directly after the constructor has been
+called, while addConfiguredInner gets the object after the attributes and
+nested children for this new object have been handled.
        
+
+
        What happens if you use more than one of the options?  Only one of the methods will be called,
+but we don't know which, this depends on the implementation of your JVM.
        
 
 
        Nested Types
        
-If your task needs to nest an arbitrary type that has been defined
-using <typedef> you have two options.
-  
          
-    
        1. public void add(Type type)
          2. 
-    
        2. public void addConfigured(Type type)
          3. 
-  
        
-  The difference between 1 and 2 is the same as between 2 and 3 in the
-  previous section.
-  
        
-    For example suppose one wanted to handle objects object of type
-    org.apache.tools.ant.taskdefs.condition.Condition, one may
-    have a class:
-  
        
-  
        +
        If your task needs to nest an arbitrary type that has been defined
+using <typedef> you have two options.
        
+
          
+  
        1. public void add(Type type)
          2. 
+  
        2. public void addConfigured(Type type)
          3. 
+
        
+
        The difference between 1 and 2 is the same as between 2 and 3 in the previous section.
        
+
        For example suppose one wanted to handle objects object of
+type org.apache.tools.ant.taskdefs.condition.Condition, one may have a class:
        
+
         public class MyTask extends Task {
     private List conditions = new ArrayList();
     public void add(Condition c) {
@@ -283,9 +231,7 @@ public class MyTask extends Task {
      // iterator over the conditions
     }
 }
        
-  
        
-    One may define and use this class like this:
-  
        
+
        One may define and use this class like this:
        
 
         <taskdef name="mytask" classname="MyTask" classpath="classes"/>
 <typedef name="condition.equals"
@@ -293,9 +239,7 @@ public class MyTask extends Task {
 <mytask>
     <condition.equals arg1="${debug}" arg2="true"/>
 </mytask>
        
-  
        
-    A more complicated example follows:
-  
        
+
        A more complicated example follows:
        
 
         public class Sample {
     public static class MyFileSelector implements FileSelector {
@@ -325,11 +269,9 @@ public class Sample {
         public void setCount(int c) {}
     }
 }
        
-  
        
-    This class defines a number of static classes that implement/extend
-      Path, MyFileSelector and MyInterface. These may be defined and used
-    as follows:
-  
        
+
        This class defines a number of static classes that
+implement/extend Path, MyFileSelector and MyInterface. These
+may be defined and used as follows:
        
 
         <typedef name="myfileselector" classname="Sample$MyFileSelector"
          classpath="classes" loaderref="classes"/>
@@ -350,26 +292,21 @@ public class Sample {
 
 
        TaskContainer
        
 
-
        The TaskContainer consists of a single method,
-addTask that basically is the same as an add method for nested elements.  The task
-instances will be configured (their attributes and nested elements
-have been handled) when your task's execute method gets
-invoked, but not before that.
        
-
-
        When we said execute would be
-called, we lied ;-).  In fact, Ant will call the perform
-method in org.apache.tools.ant.Task, which in turn calls
-execute.  This method makes sure that Build Events will be triggered.  If you
-execute the task instances nested into your task, you should also
-invoke perform on these instances instead of
+
        The TaskContainer consists of a single method, addTask that basically
+is the same as an add method for nested elements.  The task instances
+will be configured (their attributes and nested elements have been handled) when your
+task's execute method gets invoked, but not before that.
        
+
+
        When we said execute would be called, we lied ;-).  In fact,
+Ant will call the perform method in org.apache.tools.ant.Task, which in
+turn calls execute.  This method makes sure that Build
+Events will be triggered.  If you execute the task instances nested into your task, you should
+also invoke perform on these instances instead of
 execute.
        
 
 
        Example
        
-
        Let's write our own task, which prints a message on the
-System.out stream.
-The task has one attribute, called message.
        
+
        Let's write our own task, which prints a message on the System.out stream.  The task
+has one attribute, called message.
        
 
 
         package com.mydomain;
@@ -394,10 +331,9 @@ public class MyVeryOwnTask extends Task {
 
        It's really this simple ;-)
        
 
        Adding your task to the system is rather simple too:
        
 
          
-  
        1. Make sure the class that implements your task is in the classpath when
-    starting Ant.
          2. 
-  
        2. Add a <taskdef> element to your project.
-    This actually adds your task to the system.
          3. 
+  
        3. Make sure the class that implements your task is in the classpath when starting Ant.
          4. 
+  
        4. Add a <taskdef> element to your project.  This actually adds your task to
+    the system.
          5. 
   
        5. Use your task in the rest of the buildfile.
          6. 
 
        
 
@@ -415,11 +351,10 @@ public class MyVeryOwnTask extends Task {
 </project>
        
 
 
        Example 2
        
-To use a task directly from the buildfile which created it, place the
-<taskdef> declaration inside a target
-after the compilation. Use the classpath attribute of
-<taskdef> to point to where the code has just been
-compiled.
+
        To use a task directly from the buildfile which created it, place
+the <taskdef> declaration inside a target after the compilation. Use
+the classpath attribute of <taskdef> to point to where the code has
+just been compiled.
        
 
 
         <?xml version="1.0"?>
@@ -442,21 +377,19 @@ compiled.
   </target>
 </project>
        
 
-
        Another way to add a task (more permanently) is to add the task name and
-implementing class name to the default.properties file in the
-org.apache.tools.ant.taskdefs
+
        Another way to add a task (more permanently) is to add the task name and implementing class name
+to the default.properties file in the org.apache.tools.ant.taskdefs
 package. Then you can use it as if it were a built-in task.
        
 
 
        
 
        Build Events
        
 
        Ant is capable of generating build events as it performs the tasks necessary to build a project.
-Listeners can be attached to Ant to receive these events. This capability could be used, for example,
-to connect Ant to a GUI or to integrate Ant with an IDE.
-
        
-
        To use build events you need to create an ant Project object. You can then call the
-addBuildListener method to add your listener to the project. Your listener must implement
-the org.apache.tools.antBuildListener interface. The listener will receive BuildEvents
-for the following events
        
+Listeners can be attached to Ant to receive these events. This capability could be used, for
+example, to connect Ant to a GUI or to integrate Ant with an IDE.
        
+
        To use build events you need to create an ant Project object. You can then call
+the addBuildListener method to add your listener to the project. Your listener must
+implement the org.apache.tools.antBuildListener interface. The listener will receive
+BuildEvents for the following events
        
 
          
   
        • Build started
          • 
   
        • Build finished
          • 
@@ -467,49 +400,45 @@ for the following events
          
   
        • Message logged
          • 
 
        
 
-
        If the build file invokes another build file via
-<ant> or
-<subant> or uses
-<antcall>, you are creating a
-new Ant "project" that will send target and task level events of its
-own but never sends build started/finished events. Since Ant 1.6.2,
-BuildListener interface has an extension named
+
        If the build file invokes another build file
+via <ant>
+or <subant> or
+uses <antcall>, you are creating a new Ant
+"project" that will send target and task level events of its own but never sends build
+started/finished events. Since Ant 1.6.2, BuildListener interface has an extension named
 SubBuildListener that will receive two new events for
        
 
          
   
        • SubBuild started
          • 
   
        • SubBuild finished
          • 
 
        
-
        If you are interested in those events, all you need to do is to
-implement the new interface instead of BuildListener (and register the
-listener, of course).
        
+
        If you are interested in those events, all you need to do is to implement the new interface
+instead of BuildListener (and register the listener, of course).
        
 
-
        If you wish to attach a listener from the command line you may use the
--listener option. For example:
        
+
        If you wish to attach a listener from the command line you may use the -listener
+option. For example:
        
 
 
        ant -listener org.apache.tools.ant.XmlLogger
        
 
 
        will run Ant with a listener that generates an XML representation of the build progress. This
-listener is included with Ant, as is the default listener, which generates the logging to standard output.
        
+listener is included with Ant, as is the default listener, which generates the logging to standard
+output.
        
 
-
        Note: A listener must not access System.out and System.err directly since output on
-these streams is redirected by Ant's core to the build event system. Accessing these
-streams can cause an infinite loop in Ant. Depending on the version of Ant, this will
-either cause the build to terminate or the JVM to run out of Stack space. A logger, also, may
-not access System.out and System.err directly. It must use the streams with which it has
-been configured.
        
+
        Note: A listener must not access System.out
+and System.err directly since output on these streams is redirected by Ant's core to
+the build event system. Accessing these streams can cause an infinite loop in Ant. Depending on the
+version of Ant, this will either cause the build to terminate or the JVM to run out of Stack
+space. A logger, also, may not access System.out and System.err
+directly. It must use the streams with which it has been configured.
        
 
-
        Note: All methods of a BuildListener except for the "Build
-  Started" and "Build Finished" events may occur on several threads
-  simultaneously—for example while Ant is executing
-  a <parallel> task.
        
+
        Note: All methods of a BuildListener except for the "Build Started" and "Build
+Finished" events may occur on several threads simultaneously—for example while Ant is
+executing a <parallel> task.
        
 
 
        Example
        
-Writing an adapter to your favourite log library is very easy.
-Just implement the BuildListener interface, instantiate your logger and delegate
-the message to that instance.
        
-When starting your build provide your adapter class and the log library to the
-build classpath and activate your logger via -listener option as
-described above.
+
        Writing an adapter to your favourite log library is very easy.  Just implement the BuildListener
+interface, instantiate your logger and delegate the message to that instance.
        
+
        When starting your build provide your adapter class and the log library to the build classpath
+and activate your logger via -listener option as described above.
        
 
 
         public class MyLogAdapter implements BuildListener {
@@ -540,19 +469,17 @@ public class MyLogAdapter implements BuildListener {
 
        
 
        Source code integration
        
 
-
        The other way to extend Ant through Java is to make changes to existing tasks, which is positively encouraged.
-Both changes to the existing source and new tasks can be incorporated back into the Ant codebase, which
-benefits all users and spreads the maintenance load around.
        
+
        The other way to extend Ant through Java is to make changes to existing tasks, which is
+positively encouraged.  Both changes to the existing source and new tasks can be incorporated back
+into the Ant codebase, which benefits all users and spreads the maintenance load around.
        
 
-
        Please consult the
-Getting Involved pages on the Apache web site
-for details on how to fetch the latest source and how to submit changes for reincorporation into the
-source tree.
        
+
        Please consult the Getting
+Involved pages on the Apache web site for details on how to fetch the latest source and how to
+submit changes for reincorporation into the source tree.
        
 
-
        Ant also has some
-task guidelines
-which provides some advice to people developing and testing tasks. Even if you intend to
-keep your tasks to yourself, you should still read this as it should be informative.
        
+
        Ant also has some task guidelines
+which provides some advice to people developing and testing tasks. Even if you intend to keep your
+tasks to yourself, you should still read this as it should be informative.