[09/16] incubator-freemarker git commit: (Some Manual adjustments regarding string literal interpolations.)

[dd...@apache.org]

(Some Manual adjustments regarding string literal interpolations.)


Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/db94e072
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/db94e072
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/db94e072

Branch: refs/heads/2.3
Commit: db94e0726416af827bdd8868f46dcfb75cbebd7b
Parents: 83a30d5
Author: ddekany <dd...@apache.org>
Authored: Sun Oct 4 14:11:03 2015 +0200
Committer: ddekany <dd...@apache.org>
Committed: Sun Oct 4 14:15:16 2015 +0200

----------------------------------------------------------------------
 src/manual/book.xml | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/db94e072/src/manual/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/book.xml b/src/manual/book.xml
index 5685b35..75aa34d 100644
--- a/src/manual/book.xml
+++ b/src/manual/book.xml
@@ -2858,6 +2858,12 @@ ${s} &lt;#-- Just to see what the value of s is --&gt;
               something like <literal>"someUrl?id=1234"</literal>, regardless
               of locale and format settings.</para>
             </warning>
+
+            <para>As when <literal>${<replaceable>...</replaceable>}</literal>
+            is used inside string <emphasis>expressions</emphasis> it's just a
+            shorthand of using the <literal>+</literal> operator, <link
+            linkend="dgui_misc_autoescaping">auto-escaping</link> is not
+            applied on it.</para>
           </section>
 
           <section xml:id="dgui_template_exp_get_character">
@@ -5271,10 +5277,12 @@ jsmith@other.com, jsmith@other.com, jsmith@other.com</programlisting>
           <literal>freemarker.core.OutputFormat</literal> instance)</phrase>.
           The output format dictates the escaping rules, which is applied on
           all <literal>${<replaceable>...</replaceable>}</literal>-s (and
-          <literal>#{<replaceable>...</replaceable>}</literal>-s). It also
-          specifies a MIME type (e.g. <literal>"text/HTML"</literal>) and a
-          canonical name (e.g. <literal>"HTML"</literal>) that the embedding
-          application/framework can leverage for its own purposes.</para>
+          <literal>#{<replaceable>...</replaceable>}</literal>-s) that aren't
+          <link linkend="dgui_misc_autoescaping_stringliteral">inside a string
+          literal</link>. It also specifies a MIME type (e.g.
+          <literal>"text/HTML"</literal>) and a canonical name (e.g.
+          <literal>"HTML"</literal>) that the embedding application/framework
+          can leverage for its own purposes.</para>
 
           <para>It's the programmer's responsibility to <link
           linkend="pgui_config_outputformatsautoesc">associate output format
@@ -5702,13 +5710,15 @@ ${"&lt;h1&gt;"?no_esc + "Foo &amp; bar" + "&lt;/h1&gt;"?no_esc}</programlisting>
           </section>
 
           <section xml:id="dgui_misc_autoescaping_stringliteral">
-            <title>Auto-escaping and ${...} inside string literals</title>
+            <title>${...} inside string literals</title>
 
-            <para>A string <emphasis>expression</emphasis> like
-            <literal>"Hello ${name}!"</literal> is just a shorthand for
-            <literal>"Hello" + name + "!"</literal>, so that
-            <literal>${<replaceable>...</replaceable>}</literal> doesn't
-            auto-escape.</para>
+            <para>When <literal>${<replaceable>...</replaceable>}</literal> is
+            used inside string <emphasis>expressions</emphasis> (e.g., in
+            <literal>&lt;#assign s = "Hello ${name}!"&gt;</literal>), it's
+            just a shorthand of using the <literal>+</literal> operator
+            (<literal>&lt;#assign s = "Hello" + name + "!"&gt;</literal>).
+            Thus, <literal>${<replaceable>...</replaceable>}</literal> inside
+            string expressions isn't auto-escaped.</para>
 
             <programlisting role="template">&lt;#-- We assume that we have "HTML" output format by default. --&gt;
 &lt;#assign name = "Foo &amp; Bar"&gt;
@@ -5717,13 +5727,13 @@ ${"&lt;h1&gt;"?no_esc + "Foo &amp; bar" + "&lt;/h1&gt;"?no_esc}</programlisting>
 ${s}
 &lt;p&gt;Hello ${name}!
 
-To prove that s didn't contain the value escaped:
+To prove that s didn't contain the value in escaped form:
 ${s?replace('&amp;'), 'and'}</programlisting>
 
             <programlisting role="output">&amp;lt;p&amp;gt;Hello Foo &amp;amp; Bar!
 &lt;p&gt;Hello Foo &amp;amp; Bar!
 
-To prove that s didn't contain the value escaped:
+To prove that s didn't contain the value in escaped form:
 &amp;lt;p&amp;gt;Hello Foo and Bar!</programlisting>
           </section>
 
@@ -26270,6 +26280,12 @@ TemplateModel x = env.getVariable("x");  // get variable x</programlisting>
               <para>Added <literal>XHTMLOutputFormat</literal> and
               <literal>TemplateXHTMLOutputModel</literal>.</para>
             </listitem>
+
+            <listitem>
+              <para>Added new built-in: <literal>is_markup_output</literal>,
+              returns <literal>true</literal> if the value is of type
+              <quote>markup output</quote>.</para>
+            </listitem>
           </itemizedlist>
         </section>
       </section>