ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Adam Hardy <adam....@cyberspaceroad.com>
Subject Re: show list of available tasks
Date Tue, 16 Mar 2004 14:15:56 GMT
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
> 
> 


-- 
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


Mime
View raw message