ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tibor Strausz <Tibor.Stra...@tridion.com>
Subject RE: My complaint about Ant docs
Date Tue, 13 Aug 2002 09:22:50 GMT
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:NirgunM@C-IV.org]
> 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:steve_l@iseran.com]
> > 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" <focusrsh@arn.net>
> > To: "Steve Loughran" <steve_l@iseran.com>
> > 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:ant-user-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: 
> <mailto:ant-user-help@jakarta.apache.org>
> 
> 
> --
> To unsubscribe, e-mail:   
> <mailto:ant-user-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: 
> <mailto:ant-user-help@jakarta.apache.org>
> 

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


Mime
View raw message