ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Erik Hatcher <jakarta-...@ehatchersolutions.com>
Subject Re: ant xdocs! it ran!
Date Mon, 17 Feb 2003 20:15:04 GMT
On Saturday, February 15, 2003, at 08:30  AM, Steve Cohen wrote:
> My take on this is hard-nosed.  Until we figure out a way to designate 
> the required/optional distinction, in **all** its complexity, I cannot 
> consider this an improvement whatever other virtues it may bring to 
> the table.  That simple column is the most useful thing to me about 
> the ant documentation.  I consult it whenever I go to write a 
> build.xml that uses a task with which I am unfamiliar.

These are certainly reasonable and soundly based comments on this.

Again, I'm not at all proposing we lose information, but rather 
re-think how that information is generated a bit.  More below...

> I know it isn't easy.  A is required unless B, C and D or E is 
> specified.  Not fun.  But necessary to any automated solution.

I think we should follow the "do not repeat yourself" and "one and only 
one representation" of validation rules as best we can in this 
situation.  Here are a few invariants that we have to work within:

- Tasks can implement very complex and even dynamic validation rules 
that are well out of reach of any type of codification except within 
Java code itself.

- Its already the case that keeping the current static HTML and the 
tasks in sync is problematic.

- The look and feel of the current documentation is not flexible.

- Tools cannot work with Ant except via introspection or by humans 
coding things manually.

Back to the original point of do not repeat ourselves... if we try to 
invent some way of codifying such validation rules in @tags we'll end 
up with the same out of sync issue.  I'd rather us err on the side of 
just using the English language (or perhaps localize it all somehow) to 
define these loose things.  This duplicates the validation rules a 
little too, still, because they'll be in Java code and also in a text 
description.  These two will be in very close proximity though.

It would be sweeter if such validation constraints could be spelled out 
in @tags and those would be taken into consideration by the engine 
rather than having to code them ourselves.  If we mark an attribute as 
@ant.attribute required="true" then we would not need to code in 
execute() to throw a BuildException if its not specified.  This is 
asking a little too much at this time, so lets stick with trying to 
document things rather than changing the core :)

That being said, there is perhaps some happy medium with the "group" 
concept that Jesse mentioned and having text descriptions of the 
validation information.  Certainly there are many attributes that are 
simply required or not and we could tighten it up and specify those 
rigidly too.

I think with some work we can probably get a good solution to make us 
all happy!  I'll mull over everyones comments in the next couple of 
weeks and see what I can come up with.

> Here's a random thought of dubious utility (especially since I have no 
> idea how you're doing this) - isn't this problem similar to designing 
> a DTD?

Except a DTD is much more limited in its rules than an Ant task could 
be.  This would be much easier if the rules were as easy to follow as a 
DTD :)

This is why <antstructure> is mostly useless :))  Is it possible to 
spell out DTD rules for <property> that accurately reflects all its 
complexity?

	Erik


Mime
View raw message