Available Task Unclear documentation? shoule I bug it or is it me?

["Patrick (Gus) Heck" <pa...@olin.edu>]

I was messing with a classpath that was built from properties, and 
suddenly had the thought that it would be nice if the properties for the 
jar files were only set if they existed (did I type in the right path to 
the jar? did I move a jar and break my build without realizing it?). I 
figured I could echo the classpath and see if I was missing something 
since the unset property would come up blank. So I looked up the 
Available task in the docs, and replaced a couple properties. I don't 
see anything in the documentation that says I can't do this.

Yet here is what I get:

Buildfile: build.xml

BUILD FAILED
build.xml:13: Unexpected element "available"

Total time: 3 seconds

I poked around a bit couldn't find anything wrong... printed the version 
of Ant with the build.sh I had made to make sure I didn't have ANT_HOME 
screwed up, and such and everything seems fine. After looking at other 
files that use availabe, it seems that available only appears inside of 
<target> but not outside. When I tested it, this appeared to be the root 
of the problem.

There is nothing in the documentation that indicates that some tasks 
(such as property) can occur outside of targets while others (like 
available) must be contained in targets. Such a restriction seems 
potentially reasonable, but it should be documented if it is there. If 
you contrast the documentation about Property and Available, you get no 
indication of this difference, and there is no reference to it in 
using.html.

So my questions are:

Is the behavior I observed likely to be a problem with my setup?
If not, is it a bug in parsing the build.xml or in available?
If this is the intended behavior, should I start a bug requesting that 
it be documented?

I don't see any reason why available should be restricted to targets 
anyway, at least not when it is checking for file existance.

Of course I can put it in an init task or something but shouldn't this 
be documented? How do I find out what other tasks can appear outside of 
targets?

Gus
(I did a search and found no bugs mentioning available)


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Available Task Unclear documentation? shoule I bug it or is it me?

["Patrick (Gus) Heck" <pa...@olin.edu>]

Diane:

    Point well taken on missing the line in using.html. It is there, I just
didn't find it. To my mind, the placement of that information is good for use
as a tutorial, and bad for someone who already knows something about build
files, and is using the manual as a reference.

For now, I suggest that each special task have a notation that it is special
in it's description something like:

This property is one of several tasks that can be used outside of a target
element.

Perhaps somewhere there ought to be a list of such tasks too. It could be
linked from the above statement and perhaps reside in taskoverview.html?

Stefan:

> We didn't have a formal vote but it seemed to be consensus that we
> should allow all tasks to live outside of <target>s.  I'll start a
> vote for this for 1.6 after 1.5 has been released.
>
> Stefan

I would vote for tasks outside of targets, or an initialization element that
acted like a task, but was guarunteed to be executed before all tasks. In
fact, I like the initialization element better. It would group all the global
stuff in one place so things cant get added in funky places that are hard to
find.What I definately don't like is having to add a depends="init" to every
stinking task in my build file, or even worse sucumb to the temptation to
only add it to the tasks that need it, and get it wrong six times, taking 10
times as long.

Gus


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Available Task Unclear documentation? shoule I bug it or is it me?

[Stefan Bodewig <bo...@apache.org>]

On Mon, 20 May 2002, Steve Loughran <st...@iseran.com> wrote:

[this == <available> is not allowed outside <target>]

>> If this is the intended behavior,
> 
> yes
> 
>> should I start a bug requesting that  it be documented?
> 
> could do, but would be closed off as invalid.

I don't think so 8-)

We didn't have a formal vote but it seemed to be consensus that we
should allow all tasks to live outside of <target>s.  I'll start a
vote for this for 1.6 after 1.5 has been released.

Stefan

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Available Task Unclear documentation? shoule I bug it or is it me?

[Steve Loughran <st...@iseran.com>]

----- Original Message -----
From: "Patrick (Gus) Heck" <pa...@olin.edu>
To: "Ant Developers List" <an...@jakarta.apache.org>
Sent: Monday, May 20, 2002 5:11 PM
Subject: Available Task Unclear documentation? shoule I bug it or is it me?


> I was messing with a classpath that was built from properties, and
> suddenly had the thought that it would be nice if the properties for the
> jar files were only set if they existed (did I type in the right path to
> the jar? did I move a jar and break my build without realizing it?). I
> figured I could echo the classpath and see if I was missing something
> since the unset property would come up blank. So I looked up the
> Available task in the docs, and replaced a couple properties. I don't
> see anything in the documentation that says I can't do this.
>
> Yet here is what I get:
>
> Buildfile: build.xml
>
> BUILD FAILED
> build.xml:13: Unexpected element "available"
>
> Total time: 3 seconds
>
> I poked around a bit couldn't find anything wrong... printed the version
> of Ant with the build.sh I had made to make sure I didn't have ANT_HOME
> screwed up, and such and everything seems fine. After looking at other
> files that use availabe, it seems that available only appears inside of
> <target> but not outside. When I tested it, this appeared to be the root
> of the problem.

yup

>
> There is nothing in the documentation that indicates that some tasks
> (such as property) can occur outside of targets while others (like
> available) must be contained in targets. Such a restriction seems
> potentially reasonable, but it should be documented if it is there.

http://jakarta.apache.org/ant/manual/using.html#example

If you are looking at the 1.4 docs then it aint there; we added some more
text precisely to reduce this confusion.

> you contrast the documentation about Property and Available, you get no
> indication of this difference, and there is no reference to it in
> using.html.

see above

>
> So my questions are:
>
> Is the behavior I observed likely to be a problem with my setup?

nope

> If not, is it a bug in parsing the build.xml or in available?

neither

> If this is the intended behavior,

yes

> should I start a bug requesting that  it be documented?

could do, but would be closed off as invalid.

> I don't see any reason why available should be restricted to targets
> anyway, at least not when it is checking for file existance.

because it is really hard to draw the line as to what should be be inside,
and what should be out. There is always a line, and you have just tripped
over it. Sorry.

> Of course I can put it in an init task or something but shouldn't this
> be documented? How do I find out what other tasks can appear outside of
> targets?

see above regarding docs. Better to file a bug about 'better error messages'
in ant itself, something like "this may be a task you cannot use outside a
target". That is something that we can still do, and I like helpful error
messages as they are more likely to be read than the docs.

-Steve



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Available Task Unclear documentation? shoule I bug it or is it me?

[Diane Holt <ho...@yahoo.com>]

--- "Patrick (Gus) Heck" <pa...@olin.edu> wrote:
> There is nothing in the documentation that indicates that some tasks 
> (such as property) can occur outside of targets while others (like 
> available) must be contained in targets. Such a restriction seems 
> potentially reasonable, but it should be documented if it is there. If 
> you contrast the documentation about Property and Available, you get no 
> indication of this difference, and there is no reference to it in 
> using.html.

>From "using.html":
    Notice that we are declaring properties outside any target.
    The <property>, <typedef> and <taskdef> tasks are special in
    that they can be declared outside any target. When you do this
    they are evaluated before any targets are executed. No other
    tasks can be declared outside targets.

Although it should probably also mention that datatypes (<fileset>,
<filelist>, <filterset>, etc.) can be at the project level as well.

> I don't see any reason why available should be restricted to targets 
> anyway, at least not when it is checking for file existance.

See:
  http://marc.theaimsgroup.com/?l=ant-dev&m=98812275927267&w=2

Diane

=====
(holtdl@yahoo.com)



__________________________________________________
Do You Yahoo!?
LAUNCH - Your Yahoo! Music Experience
http://launch.yahoo.com

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>