DO NOT REPLY [Bug 53014] New: editorial errors in manual/properties.html

[bu...@apache.org]

https://issues.apache.org/bugzilla/show_bug.cgi?id=53014

             Bug #: 53014
           Summary: editorial errors in manual/properties.html
           Product: Ant
           Version: 1.8.2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
        AssignedTo: notifications@ant.apache.org
        ReportedBy: dsb@smart.net
    Classification: Unclassified


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

DO NOT REPLY [Bug 53014] editorial errors in manual/properties.html

[bu...@apache.org]

https://issues.apache.org/bugzilla/show_bug.cgi?id=53014

--- Comment #2 from Stefan Bodewig <bo...@apache.org> 2012-04-05 04:26:33 UTC ---
Many thanks for your detailed reports, Daniel, I'll look after them soon.  One
note

(In reply to comment #1)

>   (Hey, where's the right place to suggest that the Ant project's 
>   development and/or release processes include some basic (or additional) 
>   proofreading?

The dev list 8-)

>   Fixing problems way, after they have occurred and been    
>   released, by submitting bug reports, is getting pretty tedious.)

Naturally most of the documentation has been written by software developers who
most often are not too good at technical writing and/or who do not like to
write docs anyway.  In addition many of us are not native English speakers.

Any help with improving the docs will be much appreciated.

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

DO NOT REPLY [Bug 53014] editorial errors in manual/properties.html

[bu...@apache.org]

https://issues.apache.org/bugzilla/show_bug.cgi?id=53014

--- Comment #1 from Daniel B. <ds...@smart.net> 2012-03-31 20:36:36 UTC ---
The Ant manual page manual/properties.html has a number of editorial errors.
(Along with lower-level punctuation errors, there are some higher-level
problems of wording that isn't parsable (that make no sense as it is).)


* "There are many tasks that can set properties, the most common one is the 
  property task.": - The comma should be a semicolon (or sentence break).

* "Normally property values can not be changed, once a property is set, most 
  tasks will not allow its value to be modified.":  The first comma should be 
  a semicolon (or ...).

* "... are of global scope, i.e. once they have been ...":  There should be
  a comma after "i.e.".  (See other occurrences of that problem too.)

* "comma separated list" should be "comma-separated list".

* "the targets that have been specified on the command line (the IDE, an 
  <ant> task ...) when invoking the current project.":  Something went
  wrong near "(the IDE".

* "There are three sub-interfaces of Delegate that may be useful to implement."
  (before a bulleted) list: That period should be a colon.

* The paragraph about org.apache.tools.ant.PropertyHelper$PropertySetter 
  seems to be exactly the same as the first paragraph about 
  org.apache.tools.ant.PropertyHelper$PropertyEvaluator.  (It looks like
  copy,-paste,-and-forget-to-edit error.)

* "... will be interpreted literally; that is, as '$'. ": That semicolon
  should be a comma.

* "This means you can't use easily expand properties whose":  Something
  went wrong in that wording.

* 'Expanding a "Property Name"':  Shouldn't that be "Expanding a
  Property Reference"?  (It's not really expanding the name, and it's
  definitely not replacing only the _name_--it's replacing the rest of
  the _reference_ too.  Also, the quotes don't seem to be necessary--
  unless it was to address that name-vs.-reference difference, which
  would be handled better by referring to the reference.)

* "... is invoked -all built in types ...": The hyphen doesn't have
  space on both sides.  Actually, the hyphens used like that really
  should the dashes (em-dashes, I think; with no spaces on either side).

* "Any Ant type which has been declared with a reference can also its 
  string value extracted ...": Something went wrong with the wording.

  (Hey, where's the right place to suggest that the Ant project's 
  development and/or release processes include some basic (or additional) 
  proofreading?  Fixing problems way, after they have occurred and been    
  released, by submitting bug reports, is getting pretty tedious.)

* "For example, here is how to get a listing of the files in a fileset,":
  That comma should be a colon.

* "Any Ant type which has been declared with a reference can also be used 
  as a property by using the ${ant.refid:} operation ...":  
  It's not the type which been declared, but the item of the type.

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