some nice intro (preparing for a decent distro)

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@267564 13f79535-47bb-0310-9956-ffa450edef68

LICENSE

@@ -0,0 +1,48 @@
+/*
+ * ============================================================================
+ *                   The Apache Software License, Version 1.1
+ * ============================================================================
+ * 
+ *    Copyright (C) 1999 The Apache Software Foundation. All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without modifica-
+ * tion, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of  source code must  retain the above copyright  notice,
+ *    this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * 3. The end-user documentation included with the redistribution, if any, must
+ *    include  the following  acknowledgment:  "This product includes  software
+ *    developed  by the  Apache Software Foundation  (http://www.apache.org/)."
+ *    Alternately, this  acknowledgment may  appear in the software itself,  if
+ *    and wherever such third-party acknowledgments normally appear.
+ * 
+ * 4. The names "Ant" and  "Apache Software Foundation"  must not be used to
+ *    endorse  or promote  products derived  from this  software without  prior
+ *    written permission. For written permission, please contact
+ *    apache@apache.org.
+ * 
+ * 5. Products  derived from this software may not  be called "Apache", nor may
+ *    "Apache" appear  in their name,  without prior written permission  of the
+ *    Apache Software Foundation.
+ * 
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
+ * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
+ * APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
+ * INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
+ * DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
+ * ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
+ * (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * 
+ * This software  consists of voluntary contributions made  by many individuals
+ * on behalf of the  Apache Software Foundation.  For more  information  on the 
+ * Apache Software Foundation, please see <http://www.apache.org/>.
+ *
+ */

README

@@ -1,46 +1,68 @@
-README file for the jakarta-ant workspace
------------------------------------------------------------------
-$Id$
-=================================================================
 
-This is the workspace for Ant, a Java based build tool.
+                                 A     N     T
+ 
 
-TODO List:
+  What is it? 
+  -----------
+  
+  Ant is a Java based build tool. In theory it is kind of like "make" 
+  without makes wrinkles and with the full portability of pure java code.
 
-  * Improve documentation of how to use ant, how tasks are
-    constructed, etc. 
+  
+  Why?
+  ----
+  
+  Why another build tool when there is already make, gnumake, nmake, jam, 
+  and others? Because all of those tools have limitations that its original 
+  author couldn't live with when developing software across multiple platforms. 
+  
+  Make-like tools are inherently shell based. They evaluate a set of 
+  dependencies and then execute commands not unlike what you would issue on a 
+  shell. This means that you can easily extend these tools by using or writing 
+  any program for the OS that you are working on. However, this also means that 
+  you limit yourself to the OS, or at least the OS type such as Unix, that you 
+  are working on.
+  
+  Makefiles are inherently evil as well. Anybody who has worked on them for any 
+  time has run into the dreaded tab problem. "Is my command not executing 
+  because I have a space in front of my tab!!!" said the original author of Ant 
+  way too many times. Tools like Jam took care of this to a great degree, but 
+  still use yet another format to use and remember.
+  
+  Ant is different. Instead a model where it is extended with shell based 
+  commands, it is extended using Java classes. Instead of writing shell 
+  commands, the configuration files are XML based calling out a target tree 
+  where various tasks get executed. Each task is run by an object which 
+  implements a particular Task interface.
+  
+  Granted, this removes some of the expressive power that is inherent by being 
+  able to construct a shell command such as `find . -name foo -exec rm {}` but 
+  it gives you the ability to be cross platform. To work anywhere and 
+  everywhere. And hey, if you really need to execute a shell command, Ant has 
+  an exec rule that allows different commands to be executed based on the OS 
+  that it is executing on.
 
-  * Improve error reporting on BuildException catches. Error should
-    state which task and which target was active at the time the
-    BuildException was popped.
+  The Latest Version
+  ------------------
 
-  * Improve error reporting on XML parse. Currently if the build.xml
-    file is malformed we get some sort of odd SAX exception that could
-    be better put.
+  Details of the latest version can be found on the Apache Jakarta
+  Project web site <http://jakarta.apache.org/>.
 
-  * Provide an AbstractFileCompareTask class with prebuilt "srcfile"
-    and "destfile" setter methods and whose execute method calls a
-    "updateNeeded" method.
 
-  * Transform task -- XSLT 
+  Documentation
+  -------------
 
-  * Output logs in XML -- this would be a global option of the project
-    (log location, verboseness, etc)
+  Documentation is available in HTML format, in the docs/ directory.
 
-  * Javac improvements -- support the "modern" 1.3 compiler
 
-  * Investigate some sort of command line "execute an instance of a
-    task with these parameters" entry point. Maybe a
-    `org.apache.ant.TaskMain task org.foo.BarTask attrib1=foo
-    attrib2=bar` type entry point?
+  Licensing
+  ---------
 
-  * Investigate some sort of "touch" functionality. Not sure how this
-    could be done in a portable way -- maybe append 0 bytes to a file
-    as a quick hack?
+  This software is licensed under the terms you may find in the file 
+  named "LICENSE" in this directory.
+  
 
-  * GUI front end -- examine tasks, add task properties, etc. Also,
-    one button push build of a particular target.
-
-  * Test harness. All software projects should have an automatable
-    test suite. Ant is no exception to this rule.
+  Thanks for using Ant.
 
+                                          The Apache Jakarta Project
+                                         <http://jakarta.apache.org/>

TODO

@@ -0,0 +1,42 @@
+TODO List:
+
+  * write a target rule that reacts on class presence or more generally, a way
+    to apply environment conditions that must be met in order for a target to 
+    be executed. This is _vital_ for highly componentized systems where
+    non-core parts of the software may be skipped if the required classes
+    are not present in the build classpath.
+
+  * Improve error reporting on BuildException catches. Error should
+    state which task and which target was active at the time the
+    BuildException was popped.
+
+  * Improve error reporting on XML parse. Currently if the build.xml
+    file is malformed we get some sort of odd SAX exception that could
+    be better put.
+
+  * Provide an AbstractFileCompareTask class with prebuilt "srcfile"
+    and "destfile" setter methods and whose execute method calls a
+    "updateNeeded" method.
+
+  * Transform task -- XSLT 
+
+  * Output logs in XML -- this would be a global option of the project
+    (log location, verboseness, etc)
+
+  * Javac improvements -- support the "modern" 1.3 compiler
+
+  * Investigate some sort of command line "execute an instance of a
+    task with these parameters" entry point. Maybe a
+    `org.apache.ant.TaskMain task org.foo.BarTask attrib1=foo
+    attrib2=bar` type entry point?
+
+  * Investigate some sort of "touch" functionality. Not sure how this
+    could be done in a portable way -- maybe append 0 bytes to a file
+    as a quick hack?
+
+  * GUI front end -- examine tasks, add task properties, etc. Also,
+    one button push build of a particular target.
+
+  * Test harness. All software projects should have an automatable
+    test suite. Ant is no exception to this rule.
+