geirm 01/10/10 20:44:47
Modified: xdocs user-guide.xml
docs user-guide.html
Log:
Fixed and added to section on escaping directives. There was an error,
pointed out by Paul Kmiec <[EMAIL PROTECTED]>.
Revision Changes Path
1.51 +43 -7 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -r1.50 -r1.51
--- user-guide.xml 2001/10/10 02:22:38 1.50
+++ user-guide.xml 2001/10/11 03:44:46 1.51
@@ -1548,8 +1548,14 @@
]]></source>
<p>
- If <em>$jazz</em> is true, the output is <em>Vyacheslav Ganelin</em>; if
- <em>$jazz</em> is false, there is no output. Escaping script elements
+ If <em>$jazz</em> is true, the output is
+ </p>
+<source><![CDATA[
+Vyacheslav Ganelin
+]]></source>
+
+ <p>
+ If <em>$jazz</em> is false, there is no output. Escaping script elements
alters the output. Consider the following case:
</p>
@@ -1559,10 +1565,20 @@
\#end
]]></source>
+ <p>
+ Whether <em>$jazz</em> is true or false, the output will be
+ </p>
+
+ <source><![CDATA[
+ #if($ jazz )
+ Vyacheslav Ganelin
+ #end
+ ]]></source>
+
<p>
- Whether <em>$jazz</em> is true or false, the output will be "#if(
- $jazz ) Vyacheslav Ganelin #end"; in fact, because all script elements
- are escaped the truth of <em>$jazz</em> is never checked. Suppose
+ In fact, because all script elements
+ are escaped, <em>$jazz</em> is never evaluated for it's boolean value.
+ Suppose
backslashes precede script elements that are legitimately escaped:
</p>
@@ -1573,8 +1589,28 @@
]]></source>
<p>
- In this case, if <em>$jazz</em> is true, the output is <em>\ Vyacheslav
- Ganelin \</em>. If <em>$jazz</em> is false, there is no output. Note that
+ In this case, if <em>$jazz</em> is true, the output is
+ </p>
+
+<source><![CDATA[
+\ Vyacheslav Ganelin
+\
+]]></source>
+
+ <p>
+ To understand this, note that the <code>#if( arg ) </code> when
+ ended by a newline (return) will omit the newline from the output.
+ Therefore, the body of the <code>#if()</code>
+ block follows the first '\', rendered
+ from the '\\' preceeding the <code>#if()</code>.
+ The last \ is on a different
+ line than the text beacsue there is a newline after 'Ganelin', so
+ the final \\, preceeding the <code>#end</code> is part of the
+ body of the block.
+ </p>
+
+ <p>
+ If <em>$jazz</em> is false, there is no output. Note that
things start to break if script elements are not properly escaped.
</p>
1.54 +91 -7 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -r1.53 -r1.54
--- user-guide.html 2001/10/10 02:22:38 1.53
+++ user-guide.html 2001/10/11 03:44:47 1.54
@@ -2703,8 +2703,31 @@
</table>
</div>
<p>
- If <em>$jazz</em> is true, the output is <em>Vyacheslav Ganelin</em>; if
- <em>$jazz</em> is false, there is no output. Escaping script elements
+ If <em>$jazz</em> is true, the output is
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+Vyacheslav Ganelin
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ If <em>$jazz</em> is false, there is no output. Escaping script elements
alters the output. Consider the following case:
</p>
<div align="left">
@@ -2730,10 +2753,36 @@
</tr>
</table>
</div>
+ <p>
+ Whether <em>$jazz</em> is true or false, the output will be
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+ #if($ jazz )
+ Vyacheslav Ganelin
+ #end
+ </pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
<p>
- Whether <em>$jazz</em> is true or false, the output will be "#if(
- $jazz ) Vyacheslav Ganelin #end"; in fact, because all script elements
- are escaped the truth of <em>$jazz</em> is never checked. Suppose
+ In fact, because all script elements
+ are escaped, <em>$jazz</em> is never evaluated for it's boolean value.
+ Suppose
backslashes precede script elements that are legitimately escaped:
</p>
<div align="left">
@@ -2760,8 +2809,43 @@
</table>
</div>
<p>
- In this case, if <em>$jazz</em> is true, the output is <em>\ Vyacheslav
- Ganelin \</em>. If <em>$jazz</em> is false, there is no output. Note that
+ In this case, if <em>$jazz</em> is true, the output is
+ </p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+\ Vyacheslav Ganelin
+\
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ To understand this, note that the <code>#if( arg ) </code> when
+ ended by a newline (return) will omit the newline from the output.
+ Therefore, the body of the <code>#if()</code>
+ block follows the first '\', rendered
+ from the '\\' preceeding the <code>#if()</code>.
+ The last \ is on a different
+ line than the text beacsue there is a newline after 'Ganelin', so
+ the final \\, preceeding the <code>#end</code> is part of the
+ body of the block.
+ </p>
+ <p>
+ If <em>$jazz</em> is false, there is no output. Note that
things start to break if script elements are not properly escaped.
</p>
<div align="left">
