Return-Path: 
 <dev-return-63379-apmail-ant-dev-archive=ant.apache.org@ant.apache.org>
Delivered-To: apmail-ant-dev-archive@www.apache.org
Received: (qmail 14921 invoked from network); 28 Jan 2005 02:09:25 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur-2.apache.org with SMTP; 28 Jan 2005 02:09:25 -0000
Received: (qmail 89917 invoked by uid 500); 28 Jan 2005 02:09:23 -0000
Delivered-To: apmail-ant-dev-archive@ant.apache.org
Received: (qmail 89874 invoked by uid 500); 28 Jan 2005 02:09:22 -0000
Mailing-List: contact dev-help@ant.apache.org; run by ezmlm
Precedence: bulk
List-Unsubscribe: <mailto:dev-unsubscribe@ant.apache.org>
List-Subscribe: <mailto:dev-subscribe@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 89861 invoked by uid 99); 28 Jan 2005 02:09:22 -0000
X-ASF-Spam-Status: No, hits=0.2 required=10.0
	tests=NO_REAL_NAME
X-Spam-Check-By: apache.org
Received: from ajax-1.apache.org (HELO ajax.apache.org) (192.87.106.226)
  by apache.org (qpsmtpd/0.28) with ESMTP; Thu, 27 Jan 2005 18:09:21 -0800
Received: from ajax.apache.org (ajax.apache.org [127.0.0.1])
	by ajax.apache.org (8.12.11/8.12.11) with ESMTP id j0S29IrI021208
	for <dev@ant.apache.org>; Fri, 28 Jan 2005 03:09:18 +0100
Received: (from nobody@localhost)
	by ajax.apache.org (8.12.11/8.12.11/Submit) id j0S29ItV021206;
	Fri, 28 Jan 2005 03:09:18 +0100
Date: Fri, 28 Jan 2005 03:09:18 +0100
Message-Id: <200501280209.j0S29ItV021206@ajax.apache.org>
From: bugzilla@apache.org
To: dev@ant.apache.org
Subject: DO NOT REPLY [Bug 33281]  New:  -
    Clarify project, target, property, classpath and arg documentation
X-Bugzilla-Reason: AssignedTo
X-Virus-Checked: Checked
X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N

DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG�
RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT
<http://issues.apache.org/bugzilla/show_bug.cgi?id=33281>.
ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND�
INSERTED IN THE BUG DATABASE.

http://issues.apache.org/bugzilla/show_bug.cgi?id=33281

           Summary: Clarify project, target, property, classpath and arg
                    documentation
           Product: Ant
           Version: 1.6.2
          Platform: Sun
               URL: http://http://ant.apache.org/manual/using.html#arg
        OS/Version: Solaris
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
        AssignedTo: dev@ant.apache.org
        ReportedBy: douglas.kramer@sun.com


http://ant.apache.org/manual/using.html#arg

Two suggestions for this page:

SUGGESTION 1:
The arguments section says:

     <arg value="-l -a"/>

     is a single command-line argument containing a space character.

This is a confusing example, as it appears (to anyone who knows Unix)
like two command line options (% ls -l -a), which implies it is two
arguments, not one.  (I had tried to do <arg value="-d docs">
for javadoc, which causes an error.  I thought of this as one argument 
with two parameters.)

The other problem is that this example is identical to the next one,
which is described in a contradictory fashion as "two separate 
command-line arguments".  

It would be a lot clearer to use a string that contains a space
and doesn't look like  two arguments.  Here's one that is well-known 
to many:

     <arg value="Program Files">


SUGGESTION 2:
This concerns <project>, <target>, <property>, <classpath>, and <arg>
Each of the main sections on this page do not show the element prominently
in the first sentence (or at all, for project).  This is a reference guide
after all, and who knows what a "project" is if you don't define its syntax?
Examples are not definitive.  The first few times I visited this page, I was 
unsure if this was the definitive page or not.

This makes the docs quite hard to understand or search through and find
these elements.  I think it would be sufficient to add "<target>" 
rather than "<target attrib=value>".  

If I were doing this, in addition to a reference in the first sentence,
for prominence and clarity, I would also add the syntax ahead of each 
table. Instead of:

  A target has the following attributes:

I would say:

  A <target> element has the following attributes:

-- 
Configure bugmail: http://issues.apache.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

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