Mailing-List: contact user-help@ant.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Ant Users List" <user@ant.apache.org>
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Wed, 27 Jul 2005 16:24:00 -0400
From: "Daniels, Doug" <Doug.Daniels@gdc4s.com>
Subject: RE: Improving the manual
To: Ant Users List <user@ant.apache.org>
Message-id: <003A6E8942370C4F9DF6E5F6CBD5FC84219FCD@TNTNC4SXCH.gdc4s.com>
MIME-version: 1.0
Content-type: text/plain; charset=iso-8859-1
Content-transfer-encoding: quoted-printable
Thread-Topic: Improving the manual
Thread-Index: AcWSzyhk2O97ioBRQPWelJ2MgHItMQAGbEyQ
Content-class: urn:content-classes:message

I'm willing to help out, I'm a decently experienced user, and have come =
up with my own ant scripts and read through some best practices. I think =
it'd take some time to get my scripts to be general enough to be used as =
recipes, what we use at my company is general, but only really amongst =
the many projects that we pull together here.

I think a good discussion of macrodefs, and imports would make a good =
second step topic so that they could get an idea of how to do ANT reuse. =
I think we should put together an outline of the recipes you think =
people need and what other topics need to be explained.

-----Original Message-----
From: Roedy Green [mailto:roedyg@mindprod.com]
Sent: Wednesday, July 27, 2005 1:18 PM
To: user@ant.apache.org
Subject: Improving the manual


The big problem with the Ant manual is the people who wrote it knew=20
too much. I can see various ways to make it more intelligible to the=20
first timer:

1. define a term like project or target the first time it is=20
used.  Don't even presume people know what MAKE is.  Ant should be=20
accessible to people building their first jar.

2. start off with a glossary of terms.  When writing this, suppress=20
the urge to impress or explain the full abstract generality.  Explain=20
not so much what something does as what it is FOR.

3. In the introductory examples, be specific about precisely where=20
things are. Don't say in ${src}, be extremely specific. Say in=20
c:\com\mindprod\myproject\src.  If the specificity of Windows bothers=20
you, be specific about a UNIX example. Keep in mind your readers=20
don't understand Ant yet. You can't presume they understand the way=20
it combines directories.  My biggest initial problems with ant came=20
from trying to understand where it was looking for and putting things.

4. Give recipes.  Most people don't want to understand Ant, at least=20
at first. They just want to get the job done.  How about a set of=20
graded recipes -- totally canned scripts ready to go, just change the=20
name of your projects and Main classes. Set your project up this way=20
and a even a rank novice can use ant without thinking to get jars built.
a) Simple: one main class with Genjar
b) With two resources: e.g. a *.ser file and a *.png.:
c) With dynamic classes: a wildcard tree from some other project.
d) With a meta-ant script: to run all the individual ant scripts

These recipes allow you to explain best practices. An example is 20=20
times clearer than the best prose.

5. ask experienced users to submit a library of scripts from the real=20
world, heavily commented about what they are intending to do and how=20
they are doing it.

I am willing to write, but I would need someone to correct my work,=20
since much of Ant is still a mystery to me.


Canadian Mind Products    roedyg@mindprod.com
#327 - 964 Heywood Avenue
Victoria, BC CANADA V8V 2Y5
http://mindprod.com
roedy green                (250) 361-9093 emergency


---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
For additional commands, e-mail: user-help@ant.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
For additional commands, e-mail: user-help@ant.apache.org