ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dale Anson <dan...@germane-software.com>
Subject Re: show list of available tasks
Date Tue, 16 Mar 2004 17:13:11 GMT
Actually, <description> is an Ant type, and both Target and Project may 
contain any Ant type. <description> is indeed a valid child element of 
Target. Target also happens to have a "description" attribute, it is the 
value of this attribute that is displayed with 'ant -projecthelp'. Run 
the <antstructure> task to produce a basic Ant dtd to verify.

Dale


Adam Hardy wrote:

> I agree with your second point about how to write documentation, but I 
> strongly disagree with that I should be happy because ant found a 
> <description> tag and allocated it to the <project> tag.
> 
> Ant's xml parser has got serious problems if it can steal a node from 
> inside one node and give it to another. It is obviously not valid XML. 
> OK I could have verified it myself, but surely the parser should stick 
> to the dtd / schema.
> 
> Adam
> 
> On 03/13/2004 06:00 PM Bill Rich wrote:
> 
>> I think that ant did what it should have done.  The <description> tag 
>> is for use on the
>> <project> level not the <target> level.  Ant found the project 
>> description and put it out
>> where it should.  Target descriptions are an attribute of the <target> 
>> tag.
>>
>> I think this comes down to a philosophy of how to write documentation 
>> and how it will be
>> used.  If the target description is intended to be the full 
>> documentation of what the
>> target does and how to use it then there are many other ways to 
>> implement it.  If the
>> target description is intended to be a reminder as to what the task 
>> does then it is very
>> useful now.  As a general rule (and sometimes required by contract) I 
>> document all my code
>> in enough detail that another programmer can understand what I 
>> intended the code to do
>> when I am not there to explain it.  The bulk of this documentation is 
>> contained in
>> comments with only the external view of the code exposed in 
>> "documentation" outside the
>> code.
>>
>> IMHO - I use TextPad as my editor-of-choice.  It allows me to wrap 
>> lines on the screen and
>> save them without hard returns.  This seems to give me the best 
>> flexibility for writing
>> code files.  It allows me to resize the display window as needed and 
>> still see all the
>> text for all the lines.  I can also turn the wrap off when needed.  I 
>> know there are many
>> arguments that say I should be the one who decides where to break a 
>> line and that I should
>> put in all the appropriate breaks so the lines are displayable with 
>> any old editor but my
>> time is worth something and I will tend to use the best tools I can 
>> for the job and let
>> the computer do the more mundane work.
>>
>> If any changes are made to the documentation features in ant, I would 
>> like to see a more
>> JavaDoc like form where I can put HTML tags in the description for 
>> formatting and the
>> output would be to an HTML file.  My whims not withstanding, I find 
>> the documentation
>> feature useful as is and was surprised that ant even had it at so 
>> early a release in its
>> life-cycle.
>>
>> For my most recent ant script documentation I used the -p -v flags to 
>> display the
>> documentation redirected to a file.  I have now added the appropriate 
>> HTML tags to that
>> file and saved it as HTML so I have this information available 
>> online.  I will now add
>> more detailed descriptions to the HTML file for the final pass at the 
>> documentation for
>> the ant script.  This is not a build application of ant so it needs 
>> more documentation.
>> It will be used by L10N engineers to control at set of tools so it 
>> needs more "what is
>> this for" kinds of explanations than a normal build script.
>>
>> Before closing - thanks to all the ant contributors for their efforts 
>> in bringing ant and
>> ant-contrib to their current states and for their continued efforts in 
>> improving and
>> extending them.  The ant documentation is good and the code generally 
>> does what it is
>> advertised to do.  It takes a mind-set change to use ant effectively 
>> which is the hardest
>> part of getting started in using ant, but once you shift into that 
>> mind-set things become
>> clearer.  I don't know how to document the mind-set change any better 
>> than it is already.
>> Thank you all very much.
>>
>> Bill Rich
>> Wilandra Consulting LLC
>> 1325 Addiewell Place
>> San Jose, CA  95120-3905
>> phone:      +1 408 268-2452
>> mobile:     +1 408 410-9713
>> Santa Cruz: +1 831 464-9007
>> fax:        +1 413 669-9716
>> billrich@wilandra.com or billrich@attglobal.net
>> http://www.wilandra.com
>>
>> -----Original Message-----
>> From: Adam Hardy [mailto:adam.ant@cyberspaceroad.com]
>> Sent: Saturday, March 13, 2004 2:03 AM
>> To: user@ant.apache.org
>> Subject: Re: show list of available tasks
>>
>>
>>
>>> --- Bill Rich <billrich@attglobal.net> wrote:
>>>
>>>> I think -p -v will yield a list of Major Tasks
>>>> (those tasks with a description) and Other
>>>> Tasks (those without a description).
>>
>>
>>
>> There is another issue - perhaps an enhancement :) - to do with this
>> subject:
>>
>> ant -p only picks up the description attribute on the target.
>>
>>    <target name="init" depends="init-common"
>>      description="Sets up the appserver properties and classpath">
>>    </target>
>>
>> When I was documenting my build file, like the good developer I am, my
>> descriptions were always a little bit too verbose for one line, and my
>> editor keeps wanting to wrap them, which is of course not XML.
>>
>> So I tried this:
>>
>>    <target name="init" depends="init-common">
>>      <description>
>>        Sets up the appserver properties and classpath
>>        and have more than one line bla bla bla
>>      </description>
>>    </target>
>>
>> and weird things happened. Ant -p missed it, and thought it must be a
>> private target. But ant didn't miss it entirely, it spat out the
>> description text at a random place in the output:
>>
>>
>> Buildfile: build.xml
>>
>>        Sets up the appserver properties and classpath
>>
>> Main targets:
>>
>>   all                  Clean build and dist, then compile and deploy war
>>   assemble-ear         package all required Jars into EAR
>>   clean                delete old build and dist directories
>>   compile              Compile Java sources
>>   del-deploy           del deployed app from server
>>   del-deploy-tomcat-5  Delete tomcat-5 works deploy dir & context.xml
>>   deploy-ear           deploys an EAR file to appserver
>>   deploy-war           deploy app to server (or lib if no appserver)
>>   deploy-web           deploy app to server (or lib if no appserver)
>>   deploy-web-tomcat-5  places context.xml in conf/Catalina/localhost/
>>   ejb-jar              package class files into Jars
>>   init-common          Sets up the appserver properties and classpath
>>   jar                  jars up whatever it finds in build
>>   javadoc              Create Javadoc API documentation
>>   war                  Create war file
>> Default target: deploy
>>
>>
>>
>> Bug, enhancement or other?
>> Adam
>> -- 
>> ant 1.6.0 + java 1.4.2 on Linux 2.4.20 Debian
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
>> For additional commands, e-mail: user-help@ant.apache.org
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
>> For additional commands, e-mail: user-help@ant.apache.org
>>
>>
> 
> 

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


Mime
View raw message