More Ant considerations

[Stefano Mazzocchi <st...@apache.org>]

Hi,

I'm creating Ant's build.xml for Cocoon and I tried to make it portable.
Portable in the sense that you should change just a few lines or
properties and make it work for other well-behaving projects. A sort of
build pattern that other projects can use to "look the same" to
developers and give a coherent aspect to the hosted projects.

The problem is, as usual, javadoc.

Suppose we don't care about javadoc 1.1 and we consider javadoc 1.2 as
the starting point.

Now, brain-dead javadoc does not accept wildcards as package names. Tell
me: how stupid is that? So, instead of doing some simple, clean,
portable stuff like

javadoc org.cocoon.*

I have to do specify every single package and keep this in synch with
development. This makes me wonder if the guys who wrote javadoc where
the same that had to create the javadocs for the whole java platform: I
really hope they were not.

Anyway, I propose to use Ant to patch this stupid behavior so that
something like this

 <javadoc src="$(src)" packages="org.$(name).*"/>

can work.

Also, instead of hardcoding attributed inside the task, I propose to
separate the javadoc attributed from the doclet attributes like this

 <javadoc [general attributes]>
  <doclet name="..." [doclet-attributes]/>
 </javadoc>

so that in Cocoon we could be able to use the XMLDoclet to generate the
XML javadoc and process it later on with our XSL stylesheets to keep the
graphical look & feel the same with the rest of the docs/web site. (not
ready yet, but people is working on it)

What do you think?

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche

yet another pain in my rear

[jon * <jo...@clearink.com>]

Ok,

So, it seems as though it turns out that Zip files created with
java.util.zip.* don't have a way to mark the ZipEntry's as being a certain
type, ie: the file is TEXT or BINARY. So, what does this screw up? Well, if
you take the .zip file that is created on a PC and copy it over to a unix
box and then use unzip on it (even with the -a option), then the text files
are not properly unzipped because they will have stupid ^M's in the text
files. Note that if I zip the same exact directory with WinZip and move it
over to a unix box then unzip -a works perfectly!

ZipEntry has a setExtra() method in it with absolutely no documentation on
it. getExtra() always seems to return null, even on files that have been
created with WinZip, so it is difficult to see where I'm supposed to
actually define that a file is of type TEXT or BINARY.

Arg. Anyone (especially at Sun), can you get me more information on this? I
have been trying to search the JDC bug database, but haven't found anything
relevant to this issue.

I would like the Ant Zip task to work properly.

thanks,

-jon

Re: More Ant considerations

[Co...@eng.sun.com]

>  <javadoc [general attributes]>
>   <doclet name="..." [doclet-attributes]/>
>  </javadoc>
>
> so that in Cocoon we could be able to use the XMLDoclet to generate the
> XML javadoc and process it later on with our XSL stylesheets to keep the
> graphical look & feel the same with the rest of the docs/web site. (not
> ready yet, but people is working on it)
>
> What do you think?

There are few other places where Tasks will benefit from having childs,
and it is not difficult to add it.

I think the introspection mechanism used by ant to construct Tasks ( and
Objects)
from XML is a great helper  - it will certainly help Tomcat's server.xml
( Adapters and general server config), plus even Context ( where
deployment can be greatly simplified ).

Some time ago I checked in code to do that - I removed it later because
I didn't want to have "experimental" code in ant.

I think it would be very good to go in that direction - i.e. make the
"introspection"
and "reflexion" code independent of Ant ( the  only dependency right now is

in the creation of Project and Target with new instead of Class.forName()
).

There is nothing else specific to ant in the introspection code -
regardless
of the preference to use DOM or SAX.

If you decide to implement addXXX(), please do it in a generic way ( that
can
be used outside ant ) - or just use the existing code ( XMLHelper - it
should be
somehere in Attic ).

Costin

Re: More Ant considerations

[jon * <jo...@clearink.com>]

on 11/30/99 7:38 AM, Stefano Mazzocchi <st...@apache.org> wrote:

> The problem is, as usual, javadoc.
> 
> Suppose we don't care about javadoc 1.1 and we consider javadoc 1.2 as
> the starting point.

Thanks. ;-) BTW, javadoc 1 sucks even more than javadoc 2...so I really
don't see a need to support it. ;-)

> Now, brain-dead javadoc does not accept wildcards as package names. Tell
> me: how stupid is that? So, instead of doing some simple, clean,
> portable stuff like
> 
> javadoc org.cocoon.*
> 
> I have to do specify every single package and keep this in synch with
> development. This makes me wonder if the guys who wrote javadoc where
> the same that had to create the javadocs for the whole java platform: I
> really hope they were not.

While javadoc does a really good job at what it does, it does a HORRIBLE job
at taking instructions. ;-)
 
> Anyway, I propose to use Ant to patch this stupid behavior so that
> something like this
> 
> <javadoc src="$(src)" packages="org.$(name).*"/>
> 
> can work.

This is difficult but possible. Feel free to add this feature to my code.
;-)
 
> Also, instead of hardcoding attributed inside the task, I propose to
> separate the javadoc attributed from the doclet attributes like this
> 
> <javadoc [general attributes]>
> <doclet name="..." [doclet-attributes]/>
> </javadoc>
> 
> so that in Cocoon we could be able to use the XMLDoclet to generate the
> XML javadoc and process it later on with our XSL stylesheets to keep the
> graphical look & feel the same with the rest of the docs/web site. (not
> ready yet, but people is working on it)
> 
> What do you think?

Again, this is a major change in the functionality and design of Ant.

-jon