ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bugzi...@apache.org
Subject DO NOT REPLY [Bug 33281] New: - Clarify project, target, property, classpath and arg documentation
Date Fri, 28 Jan 2005 02:09:18 GMT
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


Mime
View raw message