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 21192] New: - documentation hard to read because of incorrect block-quoting style
Date Mon, 30 Jun 2003 14:20:18 GMT
DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG 
RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT
<http://nagoya.apache.org/bugzilla/show_bug.cgi?id=21192>.
ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND 
INSERTED IN THE BUG DATABASE.

http://nagoya.apache.org/bugzilla/show_bug.cgi?id=21192

documentation hard to read because of incorrect block-quoting style

           Summary: documentation hard to read because of incorrect block-
                    quoting style
           Product: Ant
           Version: 1.5.3
          Platform: Other
        OS/Version: Other
            Status: NEW
          Severity: Normal
          Priority: Other
         Component: Documentation
        AssignedTo: dev@ant.apache.org
        ReportedBy: dsb@smart.net


Many pages in the Ant manual use a style of block quoting that is confusing,
making the documentation hard to read.  


For example, the 1.5.3 page currently at
http://ant.apache.org/manual/CoreTasks/property.html says:

     <property name="foo.dist" value="dist"/>

   sets the property foo.dist to the value "dist".

     <property file="foo.properties"/>

   reads a set of properties from a file called "foo.properties".

     <property resource="foo.properties"/>

Note how it is not immediately clear which text goes with which example.

A sentence can't start with a block quote.  It must start with some word
that is capitalized and not indented  so the reader can recognize the 
beginning of the sentence.

The simplest fix is probably to add "This:" or "This example:" like 
this:

   This:

     <property name="foo.dist" value="dist"/>

   sets the property foo.dist to the value "dist".

   This example:

     <property file="foo.properties"/>

   reads a set of properties from a file called "foo.properties".


Assuming there are documentation guidelines for task documentors, they
should guide the documentator away from Ant's current confusing pattern
and towards the standard English form.

If there are no such documentation guidelines, something should be 
created.

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


Mime
View raw message