Initial checkin of Utah Design Guide.

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

whiteboard/utah/design guide.xml

@@ -0,0 +1,82 @@
+<?xml version="1.0"?>
+<?xml-stylesheet href="docbookx.css" type="text/css"?>
+<!--DOCTYPE article SYSTEM "docbookx.dtd"-->
+<article> 
+  <artheader> 
+	 <title>Utah Design and Programmer's Guide</title> 
+	 <author> 
+		<firstname>James Duncan</firstname> 
+		<surname>Davidson</surname> 
+	 </author> 
+	 <copyright> 
+		<year>2000</year> 
+		<holder>The Apache Software Foundation</holder> 
+	 </copyright> 
+  </artheader> 
+  <para>This document describes the design goals for Utah, a proposed
+	 replacement for the current Ant build tool. I'm calling this work "Utah" as I
+	 hope to be done with it by the end of the W3C DOM Working Group meeting taking
+	 place in Orem Utah Mar 20-23. No other meaning is intended to be conveyed by
+	 the codename.</para> 
+  <sect1> 
+	 <title>History</title> 
+	 <para>Ant was originally designed as a small, lightweight
+		<trademark>Java</trademark> based build tool. It was first created out of shear
+		frustration with make and all its variants. </para> 
+	 <para>This first public version of Ant, Ant 1.0 which was released as part
+		of the Tomcat and Watchdog code drops from Sun Microsystems, was quite popular.
+		Everyone loved its simplicity. However, everyone wanted to do something
+		different. Lots of solutions were proposed, some were hacked in. At some point
+		it was necessary to take a clean look at what it was becoming and the types of
+		problems it was really intended to solve.Utah is that fresh look It is probably
+		not going to be entirely backwards compatible, but it is hoped that by starting
+		out with a fresh look at the goals and requirements of Ant, we can end up with
+		a better tool.</para> 
+  </sect1> 
+  <sect1> 
+	 <title>Design Goals</title> 
+	 <para>Simplicity: </para> 
+	 <para>Ant must be simple to use and simple to extend. Of course, the
+		definition of simple can vary depending on which audience is chosen. For Ant,
+		since it is a build tool aimed at Java developers, the goal is simplicity of
+		use and extension for a competent Java programmer.</para> 
+	 <para>Understandability: </para> 
+	 <para>The way Ant works should be clearly understandable for a first time
+		as well as a veteran user. The mechanism to extend Amsterdam must be
+		understandable. And the build file syntax must be eminently
+		understandable.</para> 
+	 <para>Extensibility: </para> 
+	 <para>Ant must provide an easy to use extensibility path. Extensions must
+		be easy to write for the programmer and easy to place where they can best be
+		used.</para> 
+  </sect1> 
+  <sect1> 
+	 <title>Runtime Conceptual Overview</title> 
+	 <para>Ant works with entities called Projects. A Project is a collection of
+		Property definitions, Task definitions, and Targets.</para> 
+	 <para>A Property is a mutable name-value pair that is scoped to the
+		Project. As Tasks within Targets are executed, the Property list of the Project
+		can be added to, Property values can be changed, and Properties can even be
+		removed. This allows runtime information to be passed to the Tasks either by
+		the user or by programmatic result of preceding Tasks.</para> 
+	 <para>A Target is a unit of work within the Project. For example, a Project
+		could have a Target that built a set of classes in development mode, another
+		Target that packaged the classes into a distributable form, and yet another
+		Target that cleaned up everything. Targets can indicate that they depend on
+		other Targets. If such a dependency is indicated, the runtime ensures that the
+		Target that is depended on is executed before executing any Tasks for the
+		current Target.</para> 
+	 <para>Targets contain Tasks. More accurately, they contain implementations
+		of a Task. For example, a Task that performs basic Java classfile compilation
+		is provided with Ant. Another task that performs the JAR operation is provided.
+		These Tasks are very different, but each implements the Task interface. Each
+		Task is configured for its purpose. When a Target is executed, the sequence of
+		Tasks within that target are executed in turn.</para> 
+	 <para>More specifically, when a Target is executed, the list of Tasks for
+		that Target is retrieved by the runtime. Each Task is created as a new object,
+		its configuration methods called with the information that is used, and then
+		the Task is executed. By performing configuration just before the Task is
+		executed, any properties that were defined or modified by other Tasks can
+		affect the currently running task.</para> 
+  </sect1>
+</article>

whiteboard/utah/docbookx.css

@@ -0,0 +1,64 @@
+
+/* Use Times New Roman for default font */
+$DOCUMENT {
+  font-family: "Times New Roman";
+  font-size: 12pt;
+  margin-top: 5px;
+  margin-left: 5px;
+}
+
+$COMMENT {
+  display: block;
+  color: purple;
+  white-space: pre;
+}
+
+$PROCINS {
+  color: black;
+  background-color: #c0c0c0;
+}
+
+abbrev, abstract, ackno, acronym, address, affiliation, alt, answer, appendix, areaset, areaspec, arg, artheader, article, artpagenums, attribution, audioobject, author, authorblurb, authorgroup, authorinitials, bibliodiv, biblioentry, bibliography, bibliomisc, bibliomixed, biblioset, blockquote, book, bookbiblio, bookinfo, bridgehead, callout, calloutlist, caption, caution, chapter, citerefentry, citetitle, cmdsynopsis, collab, collabname, colophon, command, comment, confdates, confgroup, confnum, confsponsor, conftitle, contractnum, contractsponsor, contrib, copyright, corpauthor, corpname, date, dedication, docinfo, edition, editor, entry, entrytbl, epigraph, equation, example, figure, firstname, footnote, formalpara, funcdef, funcprototype, funcsynopsis, funcsynopsisinfo, glossary, glossdef, glossdiv, glossentry, glosslist, glosssee, glossseealso, glossterm, graphicco, group, guibutton, guiicon, guilabel, guimenu, guimenuitem, guisubmenu, highlights, holder, honorific, imageobject, imageobjectco, important, index, indexdiv, indexentry, indexterm, informalequation, informalexample, informalfigure, informaltable, inlineequation, inlinemediaobject, interface, invpartnumber, isbn, issn, issuenum, itemizedlist, itermset, jobtitle, keycap, keycombo, keysym, keyword, keywordset, label, legalnotice, lineage, link, listitem, literallayout, lot, lotentry, manvolnum, mediaobject, mediaobjectco, member, menuchoice, modespec, mousebutton, msg, msgaud, msgentry, msgexplan, msginfo, msglevel, msgmain, msgorig, msgrel, msgset, msgsub, msgtext, note, objectinfo, olink, option, orderedlist, orgdiv, orgname, othercredit, othername, pagenums, para, paramdef, part, partintro, phrase, preface, primary, primaryie, printhistory, procedure, productname, productnumber, programlisting, programlistingco, pubdate, publisher, publishername, pubsnumber, qandadiv, qandaentry, qandaset, question, refclass, refdescriptor, refentry, refentrytitle, reference, refmeta, refmiscinfo, refname, refnamediv, refpurpose, refsect1, refsect1info, refsect2, refsect2info, refsect3, refsect3info, refsynopsisdiv, refsynopsisdivinfo, releaseinfo, replaceable, revhistory, revision, revnumber, revremark, row, screen, screenco, screeninfo, screenshot, secondary, secondaryie, sect1, sect1info, sect2, sect2info, sect3, sect3info, sect4, sect4info, sect5, sect5info, section, sectioninfo, see, seealso, seealsoie, seeie, seg, seglistitem, segmentedlist, segtitle, seriesinfo, seriesvolnums, set, setindex, setinfo, shortaffil, shortcut, sidebar, simpara, simplelist, simplesect, step, subject, subjectset, subjectterm, substeps, subtitle, surname, synopfragment, synopfragmentref, synopsis, table, tbody, term, tertiary, tertiaryie, textobject, tfoot, tgroup, thead, tip, title, titleabbrev, toc, tocback, tocchap, tocentry, tocfront, toclevel1, toclevel2, toclevel3, toclevel4, toclevel5, tocpart, ulink, variablelist, varlistentry, videoobject, volumenum, warning, year {
+  display: block;
+}
+
+surname {
+  display: inline;
+}
+
+firstname {
+  display: inline;
+}
+
+year {
+  display: inline;
+}
+
+holder {
+  display: inline;
+}
+
+title {
+  margin-bottom: 6pt;
+  font-weight: bold;
+  font-size: 12pt;
+  margin-top: 12pt;
+}
+
+author {
+  font-family: sans-serif;
+}
+
+article {
+  font-family: sans-serif;
+  font-size: 10pt;
+}
+
+para {
+  margin-top: 6pt;
+  margin-bottom: 6pt;
+}
+
+itemizedlist {
+  margin-left: 24pt;
+}