Return-Path: 
 <dev-return-68425-apmail-ant-dev-archive=ant.apache.org@ant.apache.org>
Delivered-To: apmail-ant-dev-archive@www.apache.org
Received: (qmail 93885 invoked from network); 14 Aug 2005 11:06:04 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 14 Aug 2005 11:06:04 -0000
Received: (qmail 69921 invoked by uid 500); 14 Aug 2005 11:06:02 -0000
Delivered-To: apmail-ant-dev-archive@ant.apache.org
Received: (qmail 69865 invoked by uid 500); 14 Aug 2005 11:06:01 -0000
Mailing-List: contact dev-help@ant.apache.org; run by ezmlm
Precedence: bulk
List-Unsubscribe: <mailto:dev-unsubscribe@ant.apache.org>
List-Help: <mailto:dev-help@ant.apache.org>
List-Post: <mailto:dev@ant.apache.org>
List-Id: "Ant Developers List" <dev.ant.apache.org>
Reply-To: "Ant Developers List" <dev@ant.apache.org>
Delivered-To: mailing list dev@ant.apache.org
Received: (qmail 69851 invoked by uid 99); 14 Aug 2005 11:06:01 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 14 Aug 2005 04:06:01 -0700
X-ASF-Spam-Status: No, hits=-0.0 required=10.0
	tests=SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (asf.osuosl.org: domain of antoine@gmx.de designates
 213.165.64.20 as permitted sender)
Received: from [213.165.64.20] (HELO mail.gmx.net) (213.165.64.20)
    by apache.org (qpsmtpd/0.29) with SMTP; Sun, 14 Aug 2005 04:06:21 -0700
Received: (qmail invoked by alias); 14 Aug 2005 11:05:57 -0000
Received: from p54B112DD.dip0.t-ipconnect.de (EHLO DJ0X820J) [84.177.18.221]
  by mail.gmx.net (mp004) with SMTP; 14 Aug 2005 13:05:57 +0200
X-Authenticated: #22961642
Message-ID: <000901c5a0c0$71e27a40$030200c0@DJ0X820J>
From: "Antoine Levy-Lambert" <antoine@gmx.de>
To: "Ant Developers List" <dev@ant.apache.org>
References: <3CD9A35A043C094EA8773DBB698E801B0376D0C3@z011134.bk.fin.local>
 <42FC2B87.2040403@it.fts-vn.com>
Subject: Re: AW: Manual + xdocs etc
Date: Sun, 14 Aug 2005 13:08:04 +0200
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook Express 6.00.2800.1506
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1506
X-Y-GMX-Trusted: 0
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Hello Kev,


Would we also not end up with problems of characters which appear in build
files and are not desirable or are
forbidden in java sources ?

Would also source files where half of the file or two third of the file
consists of ant xml examples not look strange ?

I wonder whether this is not a case of misuse.

Cheers,

Antoine

----- Original Message ----- 
From: "Kev Jackson" <kevin.jackson@it.fts-vn.com>
To: "Ant Developers List" <dev@ant.apache.org>
Sent: Friday, August 12, 2005 6:54 AM
Subject: Re: AW: Manual + xdocs etc


>
> >>I think we should reorder the existing docs along the
> >>structure which I think Erik Hatcher had conceived and which
> >>is incarned by the @ant.category tags in the source code (scm,
> >>packaging, ...).
> >>
> >>
> >
> >A "complete" list of these tags would be helpful ...
> >
> >
> >
> >
> Agreed.
>
> >
> >
> >>I am still interested by the idea of deriving the docs from
> >>the source code.
> >>Knowing that there would be about 50% to 60% of the doc (and
> >>some of the most interesting parts) which will remain outside
> >>of the source code.
> >>
> >>For instance the examples about each task,
> >>
> >>
> >
> >Maybe in the test-buildfile.
> >+ ensure that the example is really runnable
> >+ additional test case :-)
> >- no possibility for "colorizing" important parts
> >You could search for special named targets or for special comments.
> >
> ><target name="manual.echo.example1>
> >    <!-- ant.text: A message which only appears in <tt>-debug</tt> mode.
> >-->
> >    <echo message="Deleting drive C:" level="debug"/>
> ></target>
> >
> >
> I think it would be possible to include the examples in the Ant source
> too - this would make it even more clear what the code is trying to
> accomplish and would hep to prevent refactorings etc that go against the
> intended use of the code.
>
> My thought would be to include at the top of the class, an @ant.category
> to get us started, then for example something like
>
> @ant.usage.begin
> lots of correctly formatted xhtml.....
> @ant.usage.end
>
> @ant.build.begin
> lots of correctly formatted ant xml
> @ant.build.end
>
> Thoughts?
>
> Kev
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
>
>


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