ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Daniels, Doug" <Doug.Dani...@gdc4s.com>
Subject RE: Improving the manual
Date Wed, 27 Jul 2005 20:24:00 GMT
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 
too much. I can see various ways to make it more intelligible to the 
first timer:

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

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

3. In the introductory examples, be specific about precisely where 
things are. Don't say in ${src}, be extremely specific. Say in 
c:\com\mindprod\myproject\src.  If the specificity of Windows bothers 
you, be specific about a UNIX example. Keep in mind your readers 
don't understand Ant yet. You can't presume they understand the way 
it combines directories.  My biggest initial problems with ant came 
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 
at first. They just want to get the job done.  How about a set of 
graded recipes -- totally canned scripts ready to go, just change the 
name of your projects and Main classes. Set your project up this way 
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 
times clearer than the best prose.

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

I am willing to write, but I would need someone to correct my work, 
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


Mime
View raw message