i find the docs quit readable but what (maybe) is a godd idea is that there is a place where proud ant users can put examples of there build files or some place where you can post suggestions on howto use tasks ;-)
tibi > -----Original Message----- > From: Milind Nirgun [mailto:[EMAIL PROTECTED]] > Sent: Monday, August 12, 2002 9:14 PM > To: Ant Users List > Subject: RE: My complaint about Ant docs > > > > how it all fits together. (There are some small code > snippets examples > > but, again, they are written for experts.) > > I suspect that all the "experts" referred to here have become > so reading this same documentation and using Ant. > > > > PS - I've received responses from two people attempting to > > help me with my problem. No success from their > suggestions, perhaps > > because their suggestions are as cryptic as the documentation. > > Be grateful that someone actually offered to help. In the > Evil Empire you would have to pay for it (and the service > would be slower, I am sure). > > > > Speaking of pictures...there aren't any. There are ALWAYS ways of > > > making concepts clearer with illustrations. > > BUY A BOOK!! > > -Milind > > > > > > -----Original Message----- > > From: Steve Loughran [mailto:[EMAIL PROTECTED]] > > Sent: Monday, August 12, 2002 9:35 AM > > To: Carl Dreher; ant-user > > Subject: Re: My complaint about Ant docs > > > > > > > > ----- Original Message ----- > > From: "Carl Dreher" <[EMAIL PROTECTED]> > > To: "Steve Loughran" <[EMAIL PROTECTED]> > > Sent: Monday, August 12, 2002 9:18 AM > > Subject: My complaint about Ant docs > > > > > > > > I read the ANT documentation. (Awful, really, really awful.) > > > > > > Why so? Care to improve it with your own contribution? > > > > > > -steve > > > > > > Well, Ant -is- an open-source project, so any contributions > > you want to > > > make to improve on our "awful, really, really awful" > documentation, > > > please > > > feel free. > > > > > > - Diane > > > > > > ========================= > > > > > > Hi, > > > > > > I'm sending this to both of you privately rather than through the > > > mailing reflector because I don't want to start a thread > > (and subsequent > > > pissing contest) about the state of the documentation. > > > > actually, I think you should have posted it there, which is > > why I am sending > > the reply to that group. There are some valid comments, and > > people new to > > Ant provide feedback on the docs from a different perspective > > > > I would also point you at Java Development with Ant, by Loughran and > > Hatcher, shipping this week, which at 650 pages has everything from > > beginners to ant experts. > > > > Likewise, the best part of ant:tdg is that it has some > > introductory chapters > > on using ant that are fairly readable. > > > > > > > I can't get Ant to do even the most basic thing... compile > > ONE file! So > > > I'm going to rewrite the documentation? Not a good idea unless, > > > perhaps, you work for the IRS. > > > > Rewrite? No. But open source projects are built from the voluntary > > contributions of users. Ants docs are lot better than many other OSS > > projects, but we can always do with more. > > > > (NB: IRS documentation rewrite: > > a) how much money did you earn? > > b) how much have you given us? > > c) give us the rest > > d) if you are late with (c) or lied about (a) or (b), give us > > some more. > > ) > > > > > My basic complaint is that the documentation is aimed at > someone who > > > already is thoroughly familiar with the product. > > > > agreed > > > > >Imagine taking an > > > automatic transmission apart (as Dave Barry one said, "down > > to the very > > > transmission molecules"), throwing all the pieces on a > > table, taking a > > > picture of it and then declaring that it's been documented. > > That might > > > be OK for another transmission specialist but it won't help most > > > mechanics, let alone someone who is unsure of what an automatic > > > transmission is even suppose to do. > > > > I stick to manual transmissions, me. Clutches are tractable. > > But I still > > hate those bits in the Haynes manuals where it assumes that > > you know all the > > basics of the rest of the vehicle: "The clutch is under the > > big end", or > > skimp on thing they assume is so obvious they dont need to > explain how > > "before replacing the thermostat, you must remove the DOHC > > cam belt" without > > adding caveats like "if you dont put it back right your > > engine will explode > > messily somewhere down the M4" (**) > > > > > There is exactly ONE complete example in the docs, in the > > "Using Ant" > > > section, and it comes long after a bunch of technical > > definitions that > > > are completely meaningless if you don't first have the big > > picture of > > > how it all fits together. (There are some small code > > snippets examples > > > but, again, they are written for experts.) I've done a lot > > of teaching > > > and mentoring in my life and one inviolate rule is that you > > can NEVER > > > have too many examples, especially at the beginning. > > > > agreed. > > > > > > > What is needed is a "Hello World" type build file that > compiles one > > > file. The example should include the source of everything, > > including the > > > Java files. Then a Hello World-2 that compiles two file in > > different > > > directories. Then a Hello World-3 that compiles a couple > > of files and > > > includes an outside library. Etc. Build slowly with lots of > > > explanations. > > > > That is a lot of effort. Like enough to fill a book. If > > anyone wants to do > > it, we welcome it. Having just done it for a book, I am > > planning on taking a > > rest from those aspects of the documentation, though there > > are areas that > > still need covering that I may look at. In particular, I am > > planning on > > adding a better troubleshooting doc from a bit of the book > > that didnt make > > the final build. > > > > > By the way, Java Doc is NOT documentation. It is the > > equivalent of the > > > transmission picture, referenced above. Lots of > > information about the > > > pieces but absolutely no context information or any > > instructions about > > > how all the pieces fit together. Furthermore, a Java Doc > > index is NOT > > > an index at all. It is really a table of contents. > > > > um, the ant manual pages are not javadoc, they are a list of > > tasks with > > examples. The javadocs are separate. Still, I suppose in > > terms of a factual > > reference the point you are trying to make is the same. > > > > > > > Speaking of pictures...there aren't any. There are ALWAYS ways of > > > making concepts clearer with illustrations. I find it > > maddening that, > > > given how incredibly easy it is to make simple drawings and > > put images > > > in HTML, almost no open-source documentation uses this. > > > > You have to remember that most of us software engineers are > absolutely > > hopeless at illustrations. Unless its a photograph of some mountain > > somewhere, there is nothing I can contribute in that area. If > > you can... > > > > >(Interestingly, > > > the Ant documentation I downloaded has an 'images' > directory with 36 > > > images, all of which appear to be logos, none of which > > appear anywhere > > > in the documentation. Huh?) > > > > We had a competition for logos. > > > > > > > > > > Finally (yes, really, finally)...and this is a personal > > peeve ..if the > > > release says it is **for Windows**, the README (RELEASE > NOTES, etc.) > > > files should be in Windows format and NOT Unix format! I > > always have to > > > first import those docs into Word and then save them as > > MSDOS style text > > > documents. > > > > Maybe we should autogen a readme.txt from readme with file ending > > extensions. Meantime I would like to point you at jEdit > > (jEdit.org) as an > > excellent open source Java editor with built in support not > > just for ant, > > but for files with a unix extension. Because we use tools > > like this we are > > mostly oblivious to line ending details. This is useful when > > you work in the > > Java world. > > > > > > > > - Carl Dreher > > > > > > PS - I've received responses from two people attempting to > > help me with > > > my problem. No success from their suggestions, perhaps > > because their > > > suggestions are as cryptic as the documentation. > > > > Carl, > > > > The suggestions made sense to me. It is this. > > > > 1. javac -that is, the real sun javac, not just ant, only > > autoimports files > > it can find whose directory hierarchy matches its package names. > > > > You are going > > > > <javac srcdir="sql" destdir="${outputDir}"> > > <classpath refid="MyProject.path"/> > > </javac> > > > > But there is no reference there to where the utils stuff > > comes from, and > > even the sql stuff is being handed to javac outside its > > package hierarchy. > > If you point the compiler at the base of all the source, it > will work > > everything out, compiling the utils stuff as needed. Ant's > > java dependency > > checking also relies on you doing a hierarchy better. > > > > <target name="compile" depends="prepare"> > > <javac srcdir="src" destdir="${outputDir}"> > > <classpath refid="MyProject.path"/> > > </javac> > > </target> > > </project> > > > > -Steve > > > > (**) hypothetical example. > > > > > > -- > > To unsubscribe, e-mail: > <mailto:[EMAIL PROTECTED]> > For additional commands, e-mail: > <mailto:[EMAIL PROTECTED]> > > > -- > To unsubscribe, e-mail: > <mailto:[EMAIL PROTECTED]> > For additional commands, e-mail: > <mailto:[EMAIL PROTECTED]> > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
