Fix Bug 4991; add more examples of other options.

This should mark the last change to echo.html for a while. Except.

We say that message is required unless text is provided, but in fact
<echo/> is perfectly valid, is it not?


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@269972 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/CoreTasks/echo.html

@@ -9,7 +9,14 @@
 
 <h2><a name="echo">Echo</a></h2>
 <h3>Description</h3>
-<p>Echoes a message to System.out or a file.</p>
+<p>Echoes a message to the current loggers and listeners which
+means <tt>System.out</tt> unless overridden. A <tt>level</tt>
+can be specified, which controls at what logging level the message is
+filtered at. 
+<p> 
+The task can also echo to a file, in which case the option to append rather
+than overwrite the file is available, and the <tt>level</tt> option is 
+ignored</p>
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
@@ -44,16 +51,36 @@
   
 </table>
 <h3>Examples</h3>
-<pre>  &lt;echo message=&quot;Hello world&quot;/&gt;</pre>
+<pre>  &lt;echo message=&quot;Hello, world&quot;/&gt;</pre>
+<pre>  
+&lt;echo&gt;This is a longer message stretching over
+two lines.
+&lt;/echo&gt;
+</pre>
 <pre>  
 &lt;echo&gt;
 This is a longer message stretching over
-two lines.
+three lines; the first line is a blank
+&lt;/echo&gt;
+</pre>
+As XML parsers are wont to do, the first newline in the text element
+has been included in the text. 
+
+<pre>&lt;echo message=&quot;Deleting drive C:&quot; level=&quot;debug&quot; /&gt;</pre>
+A message which only appears in <tt>-debug</tt> mode.
+<pre>&lt;echo level=&quot;error&quot; &gt;
+Imminent failure in the antimatter containment facility.
+Please withdraw to safe location at least 50km away.  
 &lt;/echo&gt;
 </pre>
-<pre>&lt;echo message=&quot;Deleting drive C:&quot; 
-  level=&quot;debug&quot; /&gt;</pre>
+A message which appears even in <tt>-quiet</tt> mode.
 
+<pre>&lt;echo file="runner.csh" append="false" &gt;#\!/bin/tcsh
+java-1.3.1 -mx1024m ${project.entrypoint} $$*
+</echo></pre>
+Generate a shell script by echoing to a file.
+Note the use of a double $ symbol to stop Ant
+filtering out the single $ during variable expansion   
 <hr>
 
 <p align="center">Copyright &copy; 2000,2001 Apache Software Foundation. All rights