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 [EMAIL PROTECTED] or [EMAIL PROTECTED] http://www.wilandra.com
-----Original Message----- From: Adam Hardy [mailto:[EMAIL PROTECTED] Sent: Saturday, March 13, 2004 2:03 AM To: [EMAIL PROTECTED] Subject: Re: show list of available tasks
--- Bill Rich <[EMAIL PROTECTED]> 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
-- ant 1.6.0 + java 1.4.2 on Linux 2.4.20 Debian
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
