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:[EMAIL PROTECTED] 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 [EMAIL PROTECTED] #327 - 964 Heywood Avenue Victoria, BC CANADA V8V 2Y5 http://mindprod.com roedy green (250) 361-9093 emergency --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
