stevel 2003/07/31 23:30:01
Modified: docs/manual/CoreTasks property.html
Log:
bug #20735 "Resource" is not explained;
explained what a resource is, clarified what property files do, to field off
recurrent bugreps and show property expansion.
Revision Changes Path
1.17 +31 -3 ant/docs/manual/CoreTasks/property.html
Index: property.html
===================================================================
RCS file: /home/cvs/ant/docs/manual/CoreTasks/property.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- property.html 25 Jul 2003 14:06:35 -0000 1.16
+++ property.html 1 Aug 2003 06:30:01 -0000 1.17
@@ -19,13 +19,14 @@
<li>By supplying both the <i>name</i> and <i>refid</i> attribute.</li>
<li>By setting the <i>file</i> attribute with the filename of the property
file to load. This property file has the format as defined by the file
used
- in the class java.util.Properties.</li>
+ in the class java.util.Properties, with the same rules about how
+ non-ISO8859-1 characters must be escaped.</li>
<li>By setting the <i>url</i> attribute with the url from which to load the
properties. This url must be directed to a file that has the format as
defined
by the file used in the class java.util.Properties.</li>
<li>By setting the <i>resource</i> attribute with the resource name of the
- property file to load. This property file has the format as defined by
the
- file used in the class java.util.Properties.</li>
+ property file to load. A resource is a property file on the current
+ classpath, or on the specified classpath.</li>
<li>By setting the <i>environment</i> attribute with a prefix to use.
Properties will be defined for every environment variable by
prefixing the supplied name and a period to the name of the
variable.</li>
@@ -163,6 +164,33 @@
Note that this only works on <em>select</em> operating systems.
Two of the values are shown being echoed.
</p>
+
+<h3>Property Files</h3>
+
+As stated, this task will load in a properties file stored in the file
+system, or as a resource on a classpath. Here are some interesting facts
+about this feature
+<ol>
+<li>If the file is not there, nothing is printed except at -verbose log
+level. This lets you have optional configuration files for every
+project, that team members can customize.
+<li>The rules for this format are laid down
+<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream)">by
Sun</a>.
+This makes it hard for Team Ant to field bug reports about it.
+<li>Trailing spaces are not stripped. It may have been what you wanted.
+<li>Want unusual characters? Escape them \u0456 or \" style.
+<li>Ant Properties are expanded in the file.
+</ol>
+In-file property expansion is very cool. Learn to use it.
+<p>
+Example:
+<pre>
+build.compiler=jikes
+deploy.server=lucky
+deploy.port=8080
+deploy.url=http://${deploy.server}:${deploy.port}/
+</pre>
+
<hr>
<p align="center">Copyright © 2000-2003 Apache Software Foundation. All
rights
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
