----- 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]>
