You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2023/01/05 00:07:09 UTC

[freemarker] branch 2.3-gae updated (ea1c5eaf -> 9f120dfe)

This is an automated email from the ASF dual-hosted git repository.

ddekany pushed a change to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git


    from ea1c5eaf Mostly CFormat-related code cleanup (things spotted during forward porting into FM3)
     new 956067cb (Minor typos)
     new c4244bcc Deleted long unmaintained Chinese translation of the Manual
     new b65c56ef Fixed outdated try.freemarker link.
     new f6cd05d9 Manual: Random minor improvements
     new 9f120dfe (Missing list of predefined values in output_format JavaDoc)

The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 src/main/java/freemarker/core/Configurable.java    |     8 +-
 .../core/ExtendedDecimalFormatParser.java          |     4 +-
 .../java/freemarker/ext/jsp/JspTagModelBase.java   |     2 +-
 src/manual/en_US/book.xml                          |    55 +-
 src/manual/zh_CN/book.xml                          | 31350 -------------------
 src/manual/zh_CN/docgen-help/README                |     2 -
 src/manual/zh_CN/docgen-misc/googleAnalytics.html  |    14 -
 src/manual/zh_CN/docgen-originals/figures/README   |     2 -
 src/manual/zh_CN/docgen.cjson                      |   132 -
 src/manual/zh_CN/favicon.png                       |   Bin 1291 -> 0 bytes
 src/manual/zh_CN/figures/model2sketch.png          |   Bin 21425 -> 0 bytes
 src/manual/zh_CN/figures/overview.png              |   Bin 11837 -> 0 bytes
 src/manual/zh_CN/figures/tree.png                  |   Bin 4699 -> 0 bytes
 src/manual/zh_CN/logo.png                          |   Bin 10134 -> 0 bytes
 14 files changed, 43 insertions(+), 31526 deletions(-)
 delete mode 100644 src/manual/zh_CN/book.xml
 delete mode 100644 src/manual/zh_CN/docgen-help/README
 delete mode 100644 src/manual/zh_CN/docgen-misc/googleAnalytics.html
 delete mode 100644 src/manual/zh_CN/docgen-originals/figures/README
 delete mode 100644 src/manual/zh_CN/docgen.cjson
 delete mode 100644 src/manual/zh_CN/favicon.png
 delete mode 100644 src/manual/zh_CN/figures/model2sketch.png
 delete mode 100644 src/manual/zh_CN/figures/overview.png
 delete mode 100644 src/manual/zh_CN/figures/tree.png
 delete mode 100644 src/manual/zh_CN/logo.png


[freemarker] 02/05: Deleted long unmaintained Chinese translation of the Manual

Posted by dd...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git

commit c4244bcc2eb6fed828787359c96688158cb5b63e
Author: ddekany <dd...@apache.org>
AuthorDate: Wed Jan 4 23:24:08 2023 +0100

    Deleted long unmaintained Chinese translation of the Manual
---
 src/manual/zh_CN/book.xml                         | 31350 --------------------
 src/manual/zh_CN/docgen-help/README               |     2 -
 src/manual/zh_CN/docgen-misc/googleAnalytics.html |    14 -
 src/manual/zh_CN/docgen-originals/figures/README  |     2 -
 src/manual/zh_CN/docgen.cjson                     |   132 -
 src/manual/zh_CN/favicon.png                      |   Bin 1291 -> 0 bytes
 src/manual/zh_CN/figures/model2sketch.png         |   Bin 21425 -> 0 bytes
 src/manual/zh_CN/figures/overview.png             |   Bin 11837 -> 0 bytes
 src/manual/zh_CN/figures/tree.png                 |   Bin 4699 -> 0 bytes
 src/manual/zh_CN/logo.png                         |   Bin 10134 -> 0 bytes
 10 files changed, 31500 deletions(-)

diff --git a/src/manual/zh_CN/book.xml b/src/manual/zh_CN/book.xml
deleted file mode 100644
index e03ff448..00000000
--- a/src/manual/zh_CN/book.xml
+++ /dev/null
@@ -1,31350 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-  Licensed to the Apache Software Foundation (ASF) under one
-  or more contributor license agreements.  See the NOTICE file
-  distributed with this work for additional information
-  regarding copyright ownership.  The ASF licenses this file
-  to you under the Apache License, Version 2.0 (the
-  "License"); you may not use this file except in compliance
-  with the License.  You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-  Unless required by applicable law or agreed to in writing,
-  software distributed under the License is distributed on an
-  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-  KIND, either express or implied.  See the License for the
-  specific language governing permissions and limitations
-  under the License.
--->
-<book conformance="docgen" version="5.0" xml:lang="en"
-      xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
->
-  <info>
-    <title>FreeMarker 手册</title>
-
-    <titleabbrev>Manual</titleabbrev>
-
-    <productname>Freemarker 2.3.23</productname>
-  </info>
-
-  <preface role="index.html" xml:id="preface">
-    <title>什么是 FreeMarker?</title>
-
-    <para>FreeMarker 是一款 <emphasis>模板引擎</emphasis>: 即一种基于模板和要改变的数据,
-	并用来生成输出文本(HTML网页,电子邮件,配置文件,源代码等)的通用工具。
-	它不是面向最终用户的,而是一个Java类库,是一款程序员可以嵌入他们所开发产品的组件。</para>
-
-    <para>模板编写为FreeMarker Template Language (FTL)。它是简单的,专用的语言,
-    <emphasis>不是</emphasis> 像PHP那样成熟的编程语言。
-	那就意味着要准备数据在真实编程语言中来显示,比如数据库查询和业务运算,
-	之后模板显示已经准备好的数据。在模板中,你可以专注于如何展现数据,
-	而在模板之外可以专注于要展示什么数据。</para>
-
-    <mediaobject>
-      <imageobject>
-        <imagedata fileref="figures/overview.png"/>
-      </imageobject>
-    </mediaobject>
-
-    <para>这种方式通常被称为 <link
-    linkend="gloss.MVC">MVC (模型 视图 控制器) 模式</link>,对于动态网页来说,是一种特别流行的模式。
-    它帮助从开发人员(Java 程序员)中分离出网页设计师(HTML设计师)。设计师无需面对模板中的复杂逻辑,
-	在没有程序员来修改或重新编译代码时,也可以修改页面的样式。</para>
-
-    <para>而FreeMarker最初的设计,是被用来在MVC模式的Web开发框架中生成HTML页面的,它没有被绑定到
-	Servlet或HTML或任意Web相关的东西上。它也可以用于非Web应用环境中。</para>
-
-    <para>FreeMarker 是 <link
-    xlink:href="http://www.fsf.org/philosophy/free-sw.html">免费的</link>,
-    基于Apache许可证2.0版本发布。</para>
-
-	<para>如果你发现 <emphasis>任何错误</emphasis> (包括
-    <emphasis>语法错误</emphasis>, <emphasis>错别字</emphasis>,
-    排版错误) 或者是在文档中找到 <emphasis>误导或混淆</emphasis> ,或有其他建议,请联系原作者! 
-	Email: ddekany at users.sourceforge.net</para>
-
-
-    <para>文档翻译的任何问题(包括语法错误,错别字)或中文技术交流,可以联系译者:nanlei1987 at gmail.com,
-    或在FreeMarker的Github上Fork一份,修改之后提交Pull Request。我们共同研究,共同进步。</para>
-
-	<para>英文版文档的作者(也是FreeMarker项目的维护者)是匈牙利人,其母语非英语,那么在这种情况下,
-	翻译过程难免会有错误存在,译者结合自身多年对FreeMarker的实践力争精准,译文力求信达雅。
-	但因个人才疏学浅,水平有限,恳请广大读者批评指正。最好的方式就是使用Github了</para>
-
-	<para>手册的更新根据原作者更新,大家的反馈随时进行。但只在有阶段性成果时才会提交发布修正版本。</para>
-
-	<para>本翻译是免费的,您可以自由下载和传播,但不可用于任何商业行为。文档版权归译者本人所有,
-	原版归FreeMarker项目组所有,您可以引用其中的描述,但必须指明出处。如需用于商业行为,
-	您必须和原作者取得联系。</para>
-  </preface>
-
-  <part xml:id="dgui">
-    <title>模板开发指南</title>
-
-    <chapter xml:id="dgui_quickstart">
-      <title>入门</title>
-
-      <para>本章内容只是对 FreeMarker 进行简略的介绍,在后续章节中将会详细展开讲述。
-      不过没有关系,在阅读了本章节的内容后,就能够编写简单,但却很有用的FreeMarker模板程序了。</para>
-
-      <section xml:id="dgui_quickstart_basics">
-        <title>模板 + 数据模型 = 输出</title>
-
-        <para>假设在一个在线商店的应用系统中需要一个HTML页面,和下面这个页面类似:</para>
-
-        <programlisting role="output">&lt;html&gt;
-&lt;head&gt;
-  &lt;title&gt;Welcome!&lt;/title&gt;
-&lt;/head&gt;
-&lt;body&gt;
-  &lt;h1&gt;Welcome <emphasis>John Doe</emphasis>!&lt;/h1&gt;
-  &lt;p&gt;Our latest product:
-  &lt;a href="<emphasis>products/greenmouse.html</emphasis>"&gt;<emphasis>green mouse</emphasis>&lt;/a&gt;!
-&lt;/body&gt;
-&lt;/html&gt;</programlisting>
-
-        <para>这里的用户名(上面的"Big Joe"),应该是登录这个网页的访问者的名字,
-		并且最新产品的数据应该来自于数据库,这样它才能随时更新。那么不能直接在HTML页面中输入它们,
-		不能使用静态的HTML代码。此时,可以使用要求输出的 <emphasis role="term">模板</emphasis>。
-		模板和静态HTML是相同的,只是它会包含一些 FreeMarker 将它们变成动态内容的指令:</para>
-
-        <programlisting role="template" xml:id="example.first">&lt;html&gt;
-&lt;head&gt;
-  &lt;title&gt;Welcome!&lt;/title&gt;
-&lt;/head&gt;
-&lt;body&gt;
-  &lt;h1&gt;Welcome <emphasis>${user}</emphasis>!&lt;/h1&gt;
-  &lt;p&gt;Our latest product:
-  &lt;a href="<emphasis>${latestProduct.url}</emphasis>"&gt;<emphasis>${latestProduct.name}</emphasis>&lt;/a&gt;!
-&lt;/body&gt;
-&lt;/html&gt;</programlisting>
-
-        <para>模板文件存放在Web服务器上,就像通常存放静态HTML页面那样。当有人来访问这个页面,
-		FreeMarker将会介入执行,然后动态转换模板,用最新的数据内容替换模板中
-        <literal>${<replaceable>...</replaceable>}</literal> 的部分,
-		之后将结果发送到访问者的Web浏览器中。访问者的Web浏览器就会接收到例如第一个HTML示例那样的内容
-		(也就是没有FreeMarker指令的HTML代码),访问者也不会察觉到服务器端使用的FreeMarker。
-		(当然,存储在Web服务器端的模板文件是不会被修改的;替换也仅仅出现在Web服务器的响应中。)</para>
-
-        <para>请注意,模板并没有包含程序逻辑来查找当前的访问者是谁,或者去查询数据库获取最新的产品。
-		显示的数据是在 FreeMarker 之外准备的,通常是一些 <quote>真正的</quote> 编程语言(比如Java)
-		所编写的代码。模板作者无需知道这些值是如何计算出的。事实上,这些值的计算方式可以完全被修改,
-		而模板可以保持不变,而且页面的样式也可以完全被修改而无需改动模板。
-		当模板作者(设计师)和程序员不是同一人时,显示逻辑和业务逻辑相分离的做法是非常有用的,
-		即便模板作者和程序员是一个人,这么来做也会帮助管理应用程序的复杂性。
-		保证模板专注于显示问题(视觉设计,布局和格式化)是高效使用模板引擎的关键。</para>
-
-        <para><indexterm>
-            <primary>data-model</primary>
-          </indexterm>为模板准备的数据整体被称作为 <emphasis role="term">数据模型</emphasis>。
-		  模板作者要关心的是,数据模型是树形结构(就像硬盘上的文件夹和文件),在视觉效果上,
-		  数据模型可以是:</para>
-
-        <programlisting role="dataModel">(root)
-  |
-  +- <emphasis>user</emphasis> = "Big Joe"
-  |
-  +- <emphasis>latestProduct</emphasis>
-      |
-      +- <emphasis>url</emphasis> = "products/greenmouse.html"
-      |
-      +- <emphasis>name</emphasis> = "green mouse"</programlisting>
-
-        <note>
-          <para>上面只是一个形象化显示;数据模型不是文本格式,它来自于Java对象。
-		  对于Java程序员来说,root就像一个有 <literal>getUser()</literal> 
-		  和 <literal>getLatestProduct()</literal> 方法的Java对象,
-		  也可以有 <literal>"user"</literal> 和 <literal>"latestProducts"</literal> 
-		  键值的Java <literal>Map</literal>对象。相似地,<literal>latestProduct</literal>
-		  就像是有 <literal>getUrl()</literal> 和  <literal>getName()</literal> 方法的Java对象。</para>
-        </note>
-
-        <para>早期版本中,可以从数据模型中选取这些值,使用 <literal>user</literal> 
-		和 <literal>latestProduct.name</literal> 表达式即可。如果我们继续类推,
-		数据模型就像一个文件系统,那么 <quote>(root)</quote> 和 <literal>latestProduct</literal>
-		就对应着目录(文件夹),而 <literal>user</literal>, <literal>url</literal> 和
-        <literal>name</literal> 就是这些目录中的文件。</para>
-
-        <para>总的来说,模板和数据模型是FreeMarker来生成输出(比如第一个展示的HTML)所必须的:</para>
-
-        <para><phrase role="markedTemplate">模板</phrase> + <phrase
-        role="markedDataModel">数据模型</phrase> = <phrase
-        role="markedOutput">输出</phrase></para>
-      </section>
-
-      <section xml:id="dgui_quickstart_datamodel">
-        <title>数据模型一览</title>
-
-        <para>正如已经看到的,数据模型的基本结构是树状的。
-		这棵树可以很复杂,并且可以有很大的深度,比如:</para>
-
-        <programlisting role="dataModel"
-                        xml:id="example.qStart.dataModelWithHashes">(root)
-  |
-  +- animals
-  |   |
-  |   +- mouse
-  |   |   |   
-  |   |   +- size = "small"
-  |   |   |   
-  |   |   +- price = 50
-  |   |
-  |   +- elephant
-  |   |   |   
-  |   |   +- size = "large"
-  |   |   |   
-  |   |   +- price = 5000
-  |   |
-  |   +- python
-  |       |   
-  |       +- size = "medium"
-  |       |   
-  |       +- price = 4999
-  |
-  +- message = "It is a test"
-  |
-  +- misc
-      |
-      +- foo = "Something"</programlisting>
-
-        <para>上图中的变量扮演目录的角色(比如 root,
-        <literal>animals</literal>, <literal>mouse</literal>,
-        <literal>elephant</literal>, <literal>python</literal>,
-        <literal>misc</literal>) 被称为 <emphasis
-        role="term">hashes</emphasis> (哈希表或哈希,译者注)。哈希表存储其他变量(被称为 
-        <anchor xml:id="topic.dataModel.subVar"/><emphasis>子变量</emphasis>),
-		它们可以通过名称来查找(比如 <quote>animals</quote>,
-        <quote>mouse</quote> 或 <quote>price</quote>)。</para>
-
-        <para>存储单值的变量
-        (<literal>size</literal>, <literal>price</literal>,
-        <literal>message</literal> 和 <literal>foo</literal>) 称为
-        <emphasis role="term">scalars</emphasis> (标量,译者注)。</para>
-
-        <para><anchor xml:id="topic.qStart.accessVariables"/>如果要在模板中使用子变量,
-		那应该从根root开始指定它的路径,每级之间用点来分隔开。要访问 <literal>mouse</literal> 的
-        <literal>price</literal> ,要从root开始,首先进入到 <literal>animals</literal> ,之后访问
-        <literal>mouse</literal> ,最后访问 <literal>price</literal> 。就可以这样来写 
-		<literal>animals.mouse.price</literal>。</para>
-
-        <para>另外一种很重要的变量是 <emphasis role="term">sequences</emphasis> (序列,译者注)。
-		它们像哈希表那样存储子变量,但是子变量没有名字,它们只是列表中的项。
-		比如,在下面这个数据模型中, <literal>animals</literal> 和
-        <literal>misc.fruits</literal> 就是序列:</para>
-
-        <programlisting role="dataModel"
-                        xml:id="example.qStart.dataModelWithSequences">(root)
-  |
-  +- animals
-  |   |
-  |   +- (1st)
-  |   |   |
-  |   |   +- name = "mouse"
-  |   |   |
-  |   |   +- size = "small"
-  |   |   |
-  |   |   +- price = 50
-  |   |
-  |   +- (2nd)
-  |   |   |
-  |   |   +- name = "elephant"
-  |   |   |
-  |   |   +- size = "large"
-  |   |   |
-  |   |   +- price = 5000
-  |   |
-  |   +- (3rd)
-  |       |
-  |       +- name = "python"
-  |       |
-  |       +- size = "medium"
-  |       |
-  |       +- price = 4999
-  |
-  +- misc
-      |
-      +- fruits
-          |
-          +- (1st) = "orange"
-          |
-          +- (2nd) = "banana"</programlisting>
-
-        <para>要访问序列的子变量,可以使用方括号形式的数字索引下标。
-		索引下标从0开始(从0开始也是程序员的传统),那么第一项的索引就是0,
-		第二项的索引就是1等等。要得到第一个动物的名称的话,可以这么来写代码 
-		<literal>animals[0].name</literal>。要得到 <literal>misc.fruits</literal> 
-		中的第二项(字符串<literal>"banana"</literal>)可以这么来写 
-		<literal>misc.fruits[1]</literal>。(实践中,通常按顺序遍历序列,而不用关心索引,
-		这点会在 <link linkend="topic.tutorial.list">后续介绍</link>。)</para>
-
-        <para>标量类型可以分为如下的类别:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>字符串:就是文本,也就是任意的字符序列,比如上面提到的
-			''m'', ''o'', ''u'', ''s'', ''e''。比如 <literal>name</literal> 
-			和 <literal>size</literal> 也是字符串。</para>
-          </listitem>
-
-          <listitem>
-            <para>数字:这是数值类型,就像上面的 <literal>price</literal>。
-			在FreeMarker中,字符串 <literal>"50"</literal> 和数字 
-			<literal>50</literal> 是两种完全不同的东西。前者是两个字符的序列
-			(这恰好是人们可以读的一个数字),而后者则是可以在数学运算中直接被使用的数值。</para>
-          </listitem>
-
-          <listitem>
-            <para>日期/时间: 可以是日期-时间格式(存储某一天的日期和时间),
-			或者是日期(只有日期,没有时间),或者是时间(只有时间,没有日期)。</para>
-          </listitem>
-
-          <listitem>
-            <para>布尔值:对应着对/错(是/否,开/关等值)类似的值。
-			比如动物可以有一个 <literal>protected</literal> (受保护的,译者注) 的子变量,
-			该变量存储这个动物是否被保护起来的值。</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>总结:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>数据模型可以被看成是树形结构。</para>
-          </listitem>
-
-          <listitem>
-            <para>标量用于存储单一的值。这种类型的值可以是字符串,数字,日期/时间或者是布尔值。</para>
-          </listitem>
-
-          <listitem>
-            <para>哈希表是一种存储变量及其相关且有唯一标识名称的容器。</para>
-          </listitem>
-
-          <listitem>
-            <para>序列是存储有序变量的容器。存储的变量可以通过数字索引来检索,索引通常从0开始。</para>
-          </listitem>
-        </itemizedlist>
-
-        <note>
-          <para>还有一些其它更为高级的类型,在这里我们并没有涉及到,比如方法和指令。</para>
-        </note>
-      </section>
-
-      <section xml:id="dgui_quickstart_template">
-        <title>模板一览</title>
-
-        <para>最简单的模板通常是普通的HTML文件(或者是其他任何文本文件;
-		FreeMarker本身不属于HTML)。当客户端访问某个页面时,
-		FreeMarker要发送HTML代码至客户端浏览器中去显示。如果想要页面动起来
-		(这里指动态网页技术,译者注),那么就要在HTML中放置能被FreeMarker所解析的特殊代码片段:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para><literal>${<replaceable>...</replaceable>}</literal>:
-            FreeMarker将会输出真实的值来替换大括号内的表达式,这样的表达式被称为 <emphasis
-            role="term">interpolation</emphasis>(插值,译者注)。</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">FTL 标签</emphasis> (FreeMarker模板的语言标签):
-			FTL标签和HTML标签有一些相似之处,但是它们是FreeMarker的指令,是不会在输出中打印的。
-			这些标签的名字以 <literal>#</literal> 开头。(用户自定义的FTL标签则需要使用
-            <literal>@</literal> 来代替 <literal>#</literal>,但这属于更高级的话题了。)</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">注释:</emphasis> 注释和HTML的注释也很相似,
-			但是它们使用 <literal>&lt;#--</literal> and <literal>--&gt;</literal> 来标识。
-			不像HTML注释那样,FTL注释不会出现在输出中(不出现在访问者的页面中),
-			因为 FreeMarker会跳过它们。</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>其他任何不是FTL标签,插值或注释的内容将被视为静态文本,
-		这些东西不会被FreeMarker所解析;会被按照原样输出出来。</para>
-
-        <para>FTL标签也被称为 <emphasis role="term">指令</emphasis>。
-		这些指令在HTML的标签 (比如: <literal>&lt;table&gt;</literal> 和
-        <literal>&lt;/table&gt;</literal>) 和HTML元素 (比如:
-        <literal>table</literal> 元素) 中的关系是相同的。(如果现在还没有感觉到它们的不同,
-		那么把“FTL标签”和“指令”看做是同义词即可。)</para>
-
-        <note>
-          <para>可以在 <link
-          xlink:href="http://freemarker-online.kenshoo.com/">http://freemarker-online.kenshoo.com/</link>
-		  上很方便的尝试编写模板</para>
-        </note>
-
-        <section>
-          <title>基本指令</title>
-
-          <para>这里我们仅仅来看一些非常常用的指令,当然
-          (<link linkend="ref_directives">指令还有很多</link>)。</para>
-
-          <section>
-            <title>if 指令</title>
-
-            <para>使用 <literal>if</literal> 指令可以有条件地跳过模板的一些片段。
-			比如,假设在 <link linkend="example.first">最初的示例</link> 中,
-			想向你的老板Big Joe特别地问好,可其他人不同:</para>
-
-            <programlisting role="template">&lt;html&gt;
-&lt;head&gt;
-  &lt;title&gt;Welcome!&lt;/title&gt;
-&lt;/head&gt;
-&lt;body&gt;
-  &lt;h1&gt;
-    Welcome ${user}<emphasis>&lt;#if user == "Big Joe"&gt;</emphasis>, our beloved leader<emphasis>&lt;/#if&gt;</emphasis>!
-  &lt;/h1&gt;
-  &lt;p&gt;Our latest product:
-  &lt;a href="${latestProduct.url}"&gt;${latestProduct.name}&lt;/a&gt;!
-&lt;/body&gt;
-&lt;/html&gt;</programlisting>
-
-            <para>此时,告诉 FreeMarker,当和 <literal>"Big Joe"</literal> 相同时
-			<quote>, our beloved leader</quote> (我们最尊敬的领导,译者注) 
-			才是if条件中那唯一的 <literal>user</literal> 变量的值。
-			通常来讲,如果 <literal><replaceable>condition</replaceable></literal> 
-			是false(布尔值),那么介于 <literal>&lt;#if
-            <replaceable>condition</replaceable>&gt;</literal> 和
-            <literal>&lt;/#if&gt;</literal> 标签中的内容会被略过。</para>
-
-            <para>我们来详细说说
-            <literal><replaceable>condition</replaceable></literal> 的使用:
-			<literal>==</literal> 是用来判断它两侧的值是否相等的操作符,
-			比较的结果是布尔值,也就是true或者false。在 <literal>==</literal> 
-			的左侧,是 <link linkend="topic.qStart.accessVariables">被引用的变量</link>,
-			我们很熟悉这样的语法结构;最终它会被变量的值所替代。通常来说,
-			在指令或插值中没有被引号标注的内容都被视为变量的引用。右侧则是指定的字符串,
-			在模板中的字符串 <emphasis>只能</emphasis> 放在引号内。</para>
-
-            <para>当价格为0时,就会打印出 <quote>Pythons are free today!</quote>:</para>
-
-            <programlisting role="template">&lt;#if animals.python.price == <emphasis>0</emphasis>&gt;
-  Pythons are free today!
-&lt;/#if&gt;</programlisting>
-
-            <para>和之前示例中,字符串被直接指定相似,
-			但这里则是数字(<literal>0</literal>)被直接指定了。
-			请注意,这里的数字 <emphasis>没有</emphasis> 放在引号内。
-			如果将(<literal>"0"</literal>)放在引号中,
-			那么FreeMarker就会将其误判为字符串了(也就是字符串0,译者注)。</para>
-
-            <para>当价格不为0时,则会打印出"Pythons are not free today!":</para>
-
-            <programlisting role="template">&lt;#if animals.python.price <emphasis>!=</emphasis> 0&gt;
-  Pythons are not free today!
-&lt;/#if&gt;</programlisting>
-
-            <para>你也许就会猜测了, <literal>!=</literal> 就是<quote>不等于</quote>。</para>
-
-            <para>同时,也可以这样编来写代码(使用 <link
-            linkend="example.qStart.dataModelWithHashes">数据模型来描述哈希表</link>):</para>
-
-            <programlisting role="template">&lt;#if <emphasis>animals.python.price &lt; animals.elephant.price</emphasis>&gt;
-  Pythons are cheaper than elephants today.
-&lt;/#if&gt;</programlisting>
-
-            <para>使用 <literal>&lt;#else&gt;</literal> 
-			标签可以指定当条件为false时程序所要执行的内容。比如:</para>
-
-            <programlisting role="template">&lt;#if animals.python.price &lt; animals.elephant.price&gt;
-  Pythons are cheaper than elephants today.
-<emphasis>&lt;#else&gt;</emphasis>
-  Pythons are not cheaper than elephants today.
-&lt;/#if&gt;</programlisting>
-
-            <para>这个示例中,如果蟒蛇的价格比大象的价格低的话,
-			程序将会打印出 <quote>Pythons are cheaper than elephants today.</quote>。
-			否则会打印 <quote>Pythons are not cheaper than elephants today.</quote>。
-			后面也可以使用 <literal>elseif</literal> 来完善它:</para>
-
-            <programlisting role="template">&lt;#if animals.python.price &lt; animals.elephant.price&gt;
-  Pythons are cheaper than elephants today.
-<emphasis>&lt;#elseif animals.elephant.price &lt; animals.python.price&gt;</emphasis>
-  Elephants are cheaper than pythons today.
-&lt;#else&gt;
-  Elephants and pythons cost the same today.
-&lt;/#if&gt;</programlisting>
-
-            <para>如果变量本身就是布尔值(true/false),则可以直接让其作为 
-			<literal>if</literal> 的 <literal><replaceable>condition</replaceable></literal>
-			(判断条件,译者注):</para>
-
-            <programlisting role="template">&lt;#if animals.python.protected&gt;
-  Pythons are protected animals!
-&lt;/#if&gt;</programlisting>
-          </section>
-
-          <section>
-            <title>list 指令</title>
-
-            <anchor xml:id="topic.tutorial.list"/>
-
-            <para>当需要列表显示内容时,list指令是必须的。比如:
-			如果合并该模板到 <link
-            linkend="example.qStart.dataModelWithSequences">前面描述序列的数据模型</link> 
-			中:</para>
-
-            <programlisting role="template">&lt;p&gt;We have these animals:
-&lt;table border=1&gt;
-  <emphasis>&lt;#list animals as animal&gt;</emphasis>
-    &lt;tr&gt;&lt;td&gt;${<emphasis>animal</emphasis>.name}&lt;td&gt;${<emphasis>animal</emphasis>.price} Euros
-  <emphasis>&lt;/#list&gt;</emphasis>
-&lt;/table&gt;</programlisting>
-
-            <para>那么输出结果将会是这样的:</para>
-
-            <programlisting role="output">&lt;p&gt;We have these animals:
-&lt;table border=1&gt;
-    <emphasis>&lt;tr&gt;&lt;td&gt;mouse&lt;td&gt;50 Euros
-    &lt;tr&gt;&lt;td&gt;elephant&lt;td&gt;5000 Euros
-    &lt;tr&gt;&lt;td&gt;python&lt;td&gt;4999 Euros</emphasis>
-&lt;/table&gt;</programlisting>
-
-            <para> <literal>list</literal> 指令的一般格式为:
-            <literal> &lt;#list <replaceable>sequence</replaceable> as
-            <replaceable>loopVariable</replaceable>&gt;<replaceable>repeatThis</replaceable>&lt;/#list&gt;</literal>。
-            <literal><replaceable>repeatThis</replaceable></literal> 部分将会在给定的
-            <literal><replaceable>sequence</replaceable></literal> 遍历时在每一项中重复,
-			从第一项开始,一个接着一个。在所有的重复中,
-            <literal><replaceable>loopVariable</replaceable></literal> 将持有当前遍历项的值。
-			这个变量仅存在于 <literal>&lt;#list
-            <replaceable>...</replaceable>&gt;</literal> 和
-            <literal>&lt;/#list&gt;</literal> 标签内。</para>
-
-            <para><literal><replaceable>sequence</replaceable></literal> 可以是任意表达式,
-			比如我们可以列表显示示例数据模型中的水果,就像这样:</para>
-
-            <programlisting role="template">&lt;ul&gt;
-<emphasis>&lt;#list misc.fruits as fruit&gt;</emphasis>
-  &lt;li&gt;${fruit}
-<emphasis>&lt;/#list&gt;</emphasis>
-&lt;/ul&gt;</programlisting>
-
-            <para>你应该很熟悉表达式 <literal>misc.fruits</literal> 了; 它 <link
-            linkend="topic.qStart.accessVariables">引用了数据模型中的变量</link>。</para>
-
-            <para>上面示例中的一个问题是如果我们有0个水果,它仍然会输出一个空的
-            <literal>&lt;ul&gt;&lt;/ul&gt;</literal>,而不是什么都没有。
-			要避免这样的情况,可以这么来使用 <literal>list</literal>:</para>
-
-            <programlisting role="template">&lt;#list misc.fruits&gt;
-  &lt;ul&gt;
-   <emphasis> &lt;#items as fruit&gt;</emphasis>
-      &lt;li&gt;${fruit}
- <emphasis>   &lt;/#items&gt;</emphasis>
-  &lt;/ul&gt;
-&lt;/#list&gt;</programlisting>
-
-            <para>此时, <literal>list</literal> 指令将列表视为一个整体,
-			在 <literal>items</literal> 指令中的部分才会为每个水果重复。
-			如果我们有0个水果,那么在 <literal>list</literal> 中的所有东西都被略过了,
-			因此就不会有 <literal>ul</literal> 标签了。</para>
-
-            <para>另一个列表相关的常见任务是:使用一些分隔符来列出水果,比如逗号:</para>
-
-            <programlisting role="template">&lt;p&gt;Fruits: &lt;#list misc.fruits as fruit&gt;${fruit}<emphasis>&lt;#sep&gt;, </emphasis>&lt;/#list&gt;</programlisting>
-
-            <programlisting role="output">&lt;p&gt;Fruits: orange, banana</programlisting>
-
-            <para>被 <literal>sep</literal> 覆盖的部分(我们也可以这么来写:
-            <literal><replaceable>...</replaceable>&lt;#sep&gt;,
-            &lt;/#sep&gt;&lt;/#list&gt;</literal>) 只有当还有下一项时才会被执行。
-			因此最后一个水果后面不会有逗号。</para>
-
-            <para>再次回到这个话题,如果我们有0个水果,会怎么样?只是打印 
-            <quote>Fruits:</quote> 也没有什么不方便。
-            <literal>list</literal> 指令,也像 <literal>if</literal> 指令那样,可以有 
-            <literal>else</literal> 部分,如果列表中有0个元素时就会被执行:</para>
-
-            <programlisting role="template">&lt;p&gt;Fruits: &lt;#list misc.fruits as fruit&gt;${fruit}&lt;#sep&gt;, <emphasis>&lt;#else&gt;None</emphasis>&lt;/#list&gt;</programlisting>
-
-            <note>
-              <para>事实上,这个过于简单的示例可以这么来写,
-			  但是它使用了本主题中没有介绍的语言特性:</para>
-
-              <programlisting role="template">&lt;p&gt;Fruits: ${fruits?join(", ", "None")}</programlisting>
-            </note>
-
-            <para>所有的这些指令(<literal>list</literal>,
-            <literal>items</literal>, <literal>sep</literal>,
-            <literal>else</literal>)可以联合起来使用:</para>
-
-            <programlisting role="template">&lt;#list misc.fruits&gt;
-  &lt;p&gt;Fruits:
-  &lt;ul&gt;
-    &lt;#items as fruit&gt;
-      &lt;li&gt;${fruit}&lt;#sep&gt; and&lt;/#sep&gt;
-    &lt;/#items&gt;
-  &lt;/ul&gt;
-&lt;#else&gt;
-  &lt;p&gt;We have no fruits.
-&lt;/#list&gt;</programlisting>
-
-            <note>
-              <para>在 <link linkend="ref_directive_list">指令参考</link> 中,
-			  可以获取到更多关于这些指令的内容。</para>
-            </note>
-          </section>
-
-          <section>
-            <title>include 指令</title>
-
-            <para>使用 <literal>include</literal> 指令,
-			我们可以在模板中插入其他文件的内容。</para>
-
-            <para>假设要在一些页面中显示版权声明的信息。那么可以创建一个文件来单独包含这些版权声明,
-			之后在需要它的地方插入即可。比方说,我们可以将版权信息单独存放在页面文件
-            <literal>copyright_footer.html</literal> 中:</para>
-
-            <programlisting role="template">&lt;hr&gt;
-&lt;i&gt;
-Copyright (c) 2000 &lt;a href="http://www.acmee.com"&gt;Acmee Inc&lt;/a&gt;,
-&lt;br&gt;
-All Rights Reserved.
-&lt;/i&gt;</programlisting>
-
-            <para>当需要用到这个文件时,可以使用 <literal>include</literal> 指令来插入:</para>
-
-            <programlisting role="template">&lt;html&gt;
-&lt;head&gt;
-  &lt;title&gt;Test page&lt;/title&gt;
-&lt;/head&gt;
-&lt;body&gt;
-  &lt;h1&gt;Test page&lt;/h1&gt;
-  &lt;p&gt;Blah blah...
-<emphasis>  &lt;#include "/copyright_footer.html"&gt;</emphasis>
-&lt;/body&gt;
-&lt;/html&gt;</programlisting>
-
-            <para>此时,输出的内容为:</para>
-
-            <programlisting role="output">&lt;html&gt;
-&lt;head&gt;
-  &lt;title&gt;Test page&lt;/title&gt;
-&lt;/head&gt;
-&lt;body&gt;
-  &lt;h1&gt;Test page&lt;/h1&gt;
-  &lt;p&gt;Blah blah...
-<emphasis>&lt;hr&gt;
-&lt;i&gt;
-Copyright (c) 2000 &lt;a href="http://www.acmee.com"&gt;Acmee Inc&lt;/a&gt;,
-&lt;br&gt;
-All Rights Reserved.
-&lt;/i&gt;</emphasis>
-&lt;/body&gt;
-&lt;/html&gt;</programlisting>
-
-            <para>当修改了 <literal>copyright_footer.html</literal> 文件,
-            那么访问者在所有页面都会看到版权声明的新内容。</para>
-
-            <note>
-              <para>重用代码片段的一个更有力的方式是使用宏,但是只是更为高级的话题了,
-			  将会在 <link linkend="dgui_misc_userdefdir">后续讨论</link>。</para>
-            </note>
-          </section>
-        </section>
-
-        <section>
-          <title>联合使用指令</title>
-
-          <para>在页面上也可以多次使用指令,而且指令间也可以很容易地相互嵌套。
-		  比如,在 <literal>list</literal> 指令中嵌套 <literal>if</literal> 指令:</para>
-
-          <programlisting role="template"><emphasis>&lt;#list animals as animal&gt;</emphasis>
-      &lt;div<emphasis>&lt;#if animal.protected&gt;</emphasis><emphasis> </emphasis>class="protected"<emphasis>&lt;/#if&gt;</emphasis>&gt;
-        ${animal.name} for ${animal.price} Euros
-      &lt;/div&gt;
-<emphasis>&lt;/#list&gt;</emphasis></programlisting>
-
-          <para>请注意,FreeMarker并不解析FTL标签以外的文本、插值和注释,
-		  上面示例在HTML属性中使用FTL标签也不会有问题。</para>
-        </section>
-
-        <section>
-          <title>使用内建函数</title>
-
-          <para>内建函数很像子变量(如果了解Java术语的话,也可以说像方法),
-		  它们并不是数据模型中的东西,是 FreeMarker 在数值上添加的。
-		  为了清晰子变量是哪部分,使用 <literal>?</literal>(问号)代替 
-		  <literal>.</literal>(点)来访问它们。<anchor
-          xml:id="topic.commonlyUsedBuiltIns"/>常用内建函数的示例:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para><literal>user?html</literal> 给出 <literal>user</literal> 的HTML转义版本,
-			  比如 <literal>&amp;</literal> 会由 <literal>&amp;amp;</literal> 来代替。</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>user?upper_case</literal> 给出 <literal>user</literal> 值的大写版本
-			  (比如 <quote>JOHN DOE</quote> 来替代 <quote>John
-			  Doe</quote>)</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>animal.name?cap_first</literal> 给出 <literal>animal.name</literal> 
-			  的首字母大写版本(比如 <quote>Mouse</quote> 来替代 <quote>mouse</quote>)</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>user?length</literal> 给出 <literal>user</literal> 值中 
-			  <emphasis>字符</emphasis>的数量(对于 <quote>John Doe</quote> 来说就是8)</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>animals?size</literal> 给出 <literal>animals</literal> 序列中
-			  <emphasis>项目</emphasis> 的个数(我们示例数据模型中是3个)</para>
-            </listitem>
-
-            <listitem>
-              <para>如果在 <literal>&lt;#list animals as animal&gt;</literal> 和对应的
-              <literal>&lt;/#list&gt;</literal> 标签中:</para>
-
-              <itemizedlist>
-                <listitem>
-                  <para><literal>animal?index</literal> 给出了在 <literal>animals</literal> 
-				  中基于0开始的 <literal>animal</literal>的索引值</para>
-                </listitem>
-
-                <listitem>
-                  <para><literal>animal?counter</literal> 也像 <literal>index</literal>,
-				  但是给出的是基于1的索引值</para>
-                </listitem>
-
-                <listitem>
-                  <para><literal>animal?item_parity</literal> 基于当前计数的奇偶性,给出字符串
-                  <quote>odd</quote> 或 <quote>even</quote>。在给不同行着色时非常有用,比如在
-                  <literal>&lt;td class="${animal?item_parity}Row"&gt;</literal>中。</para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-          </itemizedlist>
-
-          <para>一些内建函数需要参数来指定行为,比如:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para><literal>animal.protected?string("Y", "N")</literal> 基于 
-			  <literal>animal.protected</literal> 的布尔值来返回字符串
-              <quote>Y</quote> 或 <quote>N</quote>。</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>animal?item_cycle('lightRow','darkRow')</literal> 是之前介绍的 
-			  <literal>item_parity</literal> 更为常用的变体形式。</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>fruits?join(", ")</literal> 通过连接所有项,将列表转换为字符串,
-			  在每个项之间插入参数分隔符(比如 <quote>orange,banana</quote>)</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>user?starts_with("J")</literal> 根据 <literal>user</literal> 
-			  的首字母是否是 <quote>J</quote> 返回布尔值true或false。</para>
-            </listitem>
-          </itemizedlist>
-
-          <para>内建函数应用可以链式操作,比如<literal>user?upper_case?html</literal> 
-		  会先转换用户名到大写形式,之后再进行HTML转义。(这就像可以链式使用
-		  <literal>.</literal>(点)一样)</para>
-
-          <para>可以阅读 <link linkend="ref_builtins">全部内建函数参考</link>。</para>
-        </section>
-
-        <section>
-          <title>处理不存在的变量</title>
-
-          <para>数据模型中经常会有可选的变量(也就是说有时并不存在)。
-		  除了一些典型的人为原因导致失误外,FreeMarker 绝不能容忍引用不存在的变量,
-		  除非明确地告诉它当变量不存在时如何处理。这里来介绍两种典型的处理方法。</para>
-
-          <para><phrase role="forProgrammers">这部分对程序员而言: 
-		  一个不存在的变量和一个是 <literal>null</literal> 值的变量,
-		  对于FreeMarker来说是一样的,所以这里所指的"丢失"包含这两种情况。</phrase></para>
-
-          <para>不论在哪里引用变量,都可以指定一个默认值来避免变量丢失这种情况,
-		  通过在变量名后面跟着一个 <literal>!</literal>(叹号,译者注)和默认值。
-		  就像下面的这个例子,当 <literal>user</literal> 不存在于数据模型时,
-		  模板将会将 <literal>user</literal> 的值表示为字符串 
-		  <literal>"visitor"</literal>。(当 <literal>user</literal> 存在时,
-		  模板就会表现出 <literal>${user}</literal> 的值):</para>
-
-          <programlisting role="template">&lt;h1&gt;Welcome ${user<emphasis>!"visitor"</emphasis>}!&lt;/h1&gt;</programlisting>
-
-          <para>也可以在变量名后面通过放置 <literal>??</literal> 
-		  来询问一个变量是否存在。将它和 <literal>if</literal> 指令合并,
-		  那么如果 <literal>user</literal> 变量不存在的话将会忽略整个问候的代码段:</para>
-
-          <programlisting role="template">&lt;#if <emphasis>user??</emphasis>&gt;&lt;h1&gt;Welcome ${user}!&lt;/h1&gt;&lt;/#if&gt;</programlisting>
-
-          <para>关于多级访问的变量,比如 <literal>animals.python.price</literal>,
-		  书写代码:<literal>animals.python.price!0</literal> 
-		  当且仅当 <literal>animals.python</literal> 永远存在,
-		  而仅仅最后一个子变量 <literal>price</literal> 可能不存在时是正确的
-		  (这种情况下我们假设价格是 <literal>0</literal>)。
-		  如果 <literal>animals</literal> 或 <literal>python</literal> 不存在,
-		  那么模板处理过程将会以"未定义的变量"错误而停止。为了防止这种情况的发生,
-		  可以如下这样来编写代码 <literal>(animals.python.price)!0</literal>。
-		  这种情况就是说 <literal>animals</literal> 或 <literal>python</literal> 不存在时,
-		  表达式的结果是 <literal>0</literal>。对于 <literal>??</literal> 
-		  也是同样用来的处理这种逻辑的; 将 <literal>animals.python.price??</literal> 对比 
-		  <literal>(animals.python.price)??</literal>来看。</para>
-        </section>
-      </section>
-    </chapter>
-
-    <chapter xml:id="dgui_datamodel">
-      <title>数值,类型</title>
-
-      <section xml:id="dgui_datamodel_basics">
-        <title>基本内容</title>
-
-        <note>
-          <para>这里假设你已经阅读完 <xref linkend="dgui_quickstart"/> 章节的内容了。</para>
-        </note>
-
-        <para>理解数值和类型的概念是理解数据模型的关键和基础。
-		但数值和类型的概念并不局限于数据模型,下面你就会看到了。</para>
-
-        <section xml:id="topic.value">
-          <title>什么是数值?</title>
-
-          <indexterm>
-            <primary>value</primary>
-          </indexterm>
-
-          <para><phrase role="forProgrammers">这部分对于程序员来说可以直接跳过的。</phrase></para>
-
-          <para>正如你知道的,来自于每天所使用的数字,比如16,0.5等这些用语就是 
-		  <emphasis>数值</emphasis> 的示例,也就是数字。在计算机语言中,
-		  这些用语有着更广泛的含义,比如数值并不一定是数字类型值,比如面这个数据模型:</para>
-
-          <programlisting role="dataModel" xml:id="example.stdDataModel">(root)
- |
- +- user = "Big Joe"
- |
- +- today = Jul 6, 2007
- |
- +- todayHoliday = false
- |
- +- lotteryNumbers
- |   |
- |   +- (1st) = 20
- |   |
- |   +- (2st) = 14
- |   |
- |   +- (3rd) = 42
- |   |
- |   +- (4th) = 8
- |   |
- |   +- (5th) = 15
- |
- +- cargo
-     |
-     +- name = "coal"
-     |
-     +- weight = 40
-</programlisting>
-
-          <para>变量 <literal>user</literal> 的 <emphasis>value</emphasis> 
-		  是"Big Joe"(字符串), <literal>today</literal> 的 <emphasis>value</emphasis> 
-		  是 Jul 6, 2007 (日期),<literal>todayHoliday</literal> 的 
-		  <emphasis>value</emphasis> 是false(布尔值,比如yes/no等值)。
-          <literal>lotteryNumbers</literal> 的 <emphasis>value</emphasis> 
-		  是包含20,14, 42, 8, 15的序列。当然在这种意义上,
-		  <literal>lotteryNumbers</literal> 是多值类型。它 <emphasis>包含</emphasis> 
-		  多个值(比如,其中的第二项的 <emphasis>value</emphasis> 是14),但是 
-		  <literal>lotteryNumbers</literal> 本身还是单值。它就像一个装有其它很多东西的盒子
-		  (或称之为容器,译者注),但盒子作为整体还是视作单独的。最后还有一个数值 
-		  <literal>cargo</literal>,它的 <emphasis>value</emphasis> 是一个哈希表
-		  (也是类似盒子一样的东西)。所以说,数值就是存储在变量中的(比如,在 
-		  <literal>user</literal> 或 <literal>cargo</literal> 或 
-		  <literal>cargo.name</literal> 中)的那个东西。但是,
-		  不需要存储于变量之中的数值也可以称之为数值,比如下面的数字100:</para>
-
-          <programlisting role="template">&lt;#if cargo.weight &lt; <emphasis>100</emphasis>&gt;Light cargo&lt;/#if&gt;</programlisting>
-
-          <para>当模板被执行时,计算出的临时结果也称为数值,比如这里的20和120(它会打印120):</para>
-
-          <programlisting role="template">${cargo.weight / 2 + 100}</programlisting>
-
-          <para>这里针对最后一种表示进行解释:有两个数,40(货物的重量)和2,
-		  相除的结果是20,这是一个新计算出来的数值。然后,把它和100相加,
-		  那么120就计算出来了,接着就打印出来。
-		  (<literal>${<replaceable>...</replaceable>}</literal>),之后模板继续向下执行,
-		  直到所有结果都计算出来。</para>
-
-          <para>现在你应该能体会到数值这个词的含义了。</para>
-        </section>
-
-        <section>
-          <title>什么是类型?</title>
-
-          <para>数值中非常重要的一个概念就是类型。比方说,变量 
-		  <literal>user</literal> 的类型是字符串,变量 <literal>lotteryNumbers</literal> 
-		  的类型是序列。数值的类型这个概念非常的重要,因为它决定了这些数值可以在哪里使用的最大限度。
-		  比如说,使用 <literal>${user / 2}</literal> 就是错误的,但是使用 
-		  <literal>${cargo.weight / 2}</literal> 就能计算出结果,为20,
-		  因为算术中的除法仅对数字类型的值有效,而不能用于字符串。
-		  仅当 <literal>cargo</literal> 是一个哈希表变量时,表达式 <literal>cargo.name</literal> 
-		  才可以使用点。也可以用 <literal>&lt;#list <replaceable>...</replaceable>&gt;</literal> 
-		  指令来遍历序列。而 <literal>&lt;#if ...&gt;</literal> 指令的条件只能是布尔值等。</para>
-
-          <note>
-            <para>这里说一点点的术语:称 "布尔" 或 "布尔值" 或 "布尔类型" 都是相同的含义。</para>
-          </note>
-
-          <para xml:id="topic.multitype"><indexterm>
-              <primary>Multi-typed value</primary>
-            </indexterm>数值同时也可以含有多种类型,尽管很少这么使用。看一下下面这个数据模型
-          <literal>mouse</literal> 它本身就又是字符串,又是哈希表:</para>
-
-          <programlisting role="dataModel">(root)
- |
- +- mouse = "Yerri"
-     |
-     +- age = 12
-     |
-     +- color = "brown"</programlisting>
-
-          <para>如果用上面的数据模型合并到下面的模板中:</para>
-
-          <programlisting role="template">${mouse}       &lt;#-- uses mouse as a string --&gt;
-${mouse.age}   &lt;#-- uses mouse as a hash --&gt;
-${mouse.color} &lt;#-- uses mouse as a hash --&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">Yerri
-12
-brown</programlisting>
-        </section>
-
-        <section>
-          <title>数据模型是哈希表</title>
-
-          <para>注意观察每个数据模型的例子你也许能发现:被"(root)"所标识的内容就是哈希表类型的值。
-		  当编写如 <literal>user</literal> 这样的代码时,那就意味着要把"user"变量存储在哈希表的根上。
-		  就像编写 <literal>root.user</literal>一样,这里但并没有名"root"为的变量,
-		  那么这就起不到任何作用了。</para>
-
-          <para>某些人也许会被这种数据模型的例子所困惑,也就是说,根哈希表包含更多的哈希表或序列
-          (<literal>lotteryNumbers</literal> and <literal>cargo</literal>)。其它就没有更特殊的内容了。
-		  哈希表包含其他变量,那些变量包含其它值,这些数值可以是字符串,数字等变量,
-		  当然也可以是哈希表或序列变量。最初我们解释过的,就像字符串和数字,
-		  序列或哈希表也是一种值的表示形式。</para>
-        </section>
-      </section>
-
-      <section xml:id="dgui_datamodel_types">
-        <title>类型</title>
-
-        <para>支持的类型有:</para>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para><link linkend="dgui_datamodel_scalar"
-            os="">标量:</link></para>
-
-            <itemizedlist spacing="compact">
-              <listitem>
-                <para>字符串</para>
-              </listitem>
-
-              <listitem>
-                <para>数字</para>
-              </listitem>
-
-              <listitem>
-                <para>布尔值</para>
-              </listitem>
-
-              <listitem>
-                <para>日期/时间 (日期,时间或日期时间)</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="dgui_datamodel_container">容器:</link></para>
-
-            <itemizedlist spacing="compact">
-              <listitem>
-                <para>哈希表</para>
-              </listitem>
-
-              <listitem>
-                <para>序列</para>
-              </listitem>
-
-              <listitem>
-                <para>集合</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-
-          <listitem>
-            <para>子程序:</para>
-
-            <itemizedlist spacing="compact">
-              <listitem>
-                <para><link linkend="dgui_datamodel_method">方法和函数</link></para>
-              </listitem>
-
-              <listitem>
-                <para><link linkend="dgui_datamodel_userdefdir">用户自定义指令</link></para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-
-          <listitem>
-            <para>其它/很少使用:</para>
-
-            <itemizedlist spacing="compact">
-              <listitem>
-                <para><link linkend="dgui_datamodel_node">结点</link></para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-        </itemizedlist>
-
-        <section xml:id="dgui_datamodel_scalar">
-          <title>标量</title>
-
-          <anchor xml:id="topic.designer.scalarVariable"/>
-
-          <para>标量是最基本,最简单的数值类型,它们可以是:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para><indexterm>
-                  <primary>string</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm>字符串:表示简单的文本,例如:产品的名称。</para>
-
-              <para>如果想在模板中直接给出字符串值,而不是使用数据模型中的变量,
-			  那么将文本内容写在引号内即可,比如 <literal>"green mouse"</literal> 
-			  或 <literal>'green mouse'</literal>。(关于语法的更多细节可以在 
-			  <link linkend="dgui_template_exp_direct_string" xml:lang="">后续章节</link>中找到。)</para>
-            </listitem>
-
-            <listitem>
-              <para><indexterm>
-                  <primary>number</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm>数值:比如说,产品的价格。
-              <phrase role="forProgrammers">整数和非整数是不区分的;只有单一的数字类型。比如使用了计算器,
-			  计算3/2的结果是1.5而不是1。</phrase></para>
-
-              <para>如果要在模板中直接给出数字的值,那么可以这么来写:
-			  <literal>150</literal> 或 <literal>-90.05</literal> 
-			  或 <literal>0.001</literal>。(关于语法的更多细节可以在 <link
-              linkend="dgui_template_exp_direct_number" xml:lang="">后续章节</link>中找到。)</para>
-            </listitem>
-
-            <listitem>
-              <para><indexterm>
-                  <primary>boolean</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm>布尔值:布尔值代表了逻辑上的对或错(是或否)。比如:用户是否登录了。
-				典型的应用是使用布尔值作为  <literal>if</literal> 指令的条件,
-				比如 <literal>&lt;#if loggedIn &gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal> 或者
-              <literal>&lt;#if price == 0&gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal>;
-			  后面这个 <literal>price == 0</literal> 部分的结果就是布尔值。</para>
-
-              <para>在模板中可以使用保留字 <literal>true</literal> 
-			  和 <literal>false</literal> 来指定布尔值。</para>
-            </listitem>
-
-            <listitem>
-              <para><indexterm>
-                  <primary>date</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm><indexterm>
-                  <primary>time</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm><indexterm>
-                  <primary>date-time</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm>日期:日期变量可以存储和日期/时间相关的数据。
-				一共有三种变化:</para>
-
-              <itemizedlist>
-                <listitem>
-                  <para>日期:精确到天的日期,没有时间部分。比如April 4, 2003。</para>
-                </listitem>
-
-                <listitem>
-                  <para>时间:精确到毫秒,没有日期部分。比如10:19:18 PM。</para>
-                </listitem>
-
-                <listitem>
-                  <para>日期-时间(有时也被称为"时间戳"),比如April 4,2003 10:19:18 PM。
-				  有日期和时间两部分,时间部分的存储精确到毫秒。</para>
-                </listitem>
-              </itemizedlist>
-
-              <para>不幸的是,受到Java平台的限制,FreeMarker 有时是不能决定日期的部哪分被使用
-			  (也就是说,是日期-时间格式,日期格式还是时间格式)。
-			  这个问题的解决方法是一个的高级话题,将会在 
-			  <link linkend="ref_builtin_date_datetype">后续章节</link>讨论。</para>
-
-              <para>模板中直接定义日期数值是可以的,但这也是高级话题,将会在
-              <link linkend="ref_builtin_string_date">后续章节</link> 中进行解释。</para>
-            </listitem>
-          </itemizedlist>
-
-          <para>要记住,FreeMarker区别字符串,数字,布尔值和日期类型的值。比如,
-          字符串 <literal>"150"</literal> 看起来很像数字 <literal>150</literal>,
-		  字符串只是字符的任意序列,不能将它用于计算目的,也不能和其它数字进行比较等等。</para>
-        </section>
-
-        <section xml:id="dgui_datamodel_container">
-          <title>容器</title>
-
-          <remark>站在一个比之前更''专业''的视角上来重新解释哈希表和序列,
-		  还有一些深入的思考。</remark>
-
-          <para>这些值存在的目的是为了包含其他变量;它们只是容器。
-		  它们包含的变量通常视为  <emphasis>subvariables</emphasis>
-		  (子变量,译者注)。容器的类型有:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para><indexterm>
-                  <primary>hash</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm>哈希表:每个子变量都可以通过一个唯一的名称来查找。
-				这个名称是不受限制的字符串。哈希表 <emphasis>并不确定其中子变量的顺序</emphasis>。
-				也就是说没有第一个子变量,第二个子变量这样的说法等;变量仅仅是通过名称来访问的。
-				(就像Java语言中的HashMap一样,是实现了Hash算法的Map,不记录内部元素的顺序,
-				仅仅通过名称来访问。译者注)</para>
-            </listitem>
-
-            <listitem>
-              <para><indexterm>
-                  <primary>sequence</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm>序列:每个子变量通过一个整数来标识。第一个子变量的标识符是0,
-				第二个是1,第三个是2,这样来类推,而且子变量是有顺序的。这些数次通常被称为 
-				<emphasis>indexes</emphasis>(索引,译者注)。序列通常比较密集,也就是所有的索引,
-				包括最后一个子变量的,它们和子变量都是相关联的,但不是绝对必要的。
-				子变量的类型也并不需要完全一致。</para>
-            </listitem>
-
-            <listitem>
-              <para><indexterm>
-                  <primary>collection</primary>
-
-                  <secondary>FTL 值类型</secondary>
-                </indexterm>集合:从模板设计者角度来看,集合是有限制的序列。不能获取集合的大小,
-				也不能通过索引取出集合中的子变量,但是它们仍然可以通过 
-				<link linkend="ref.directive.list"><literal>list</literal> 指令</link>来遍历。</para>
-            </listitem>
-          </itemizedlist>
-
-          <para>请注意,一个值也可有多种类型 
-		  <link linkend="topic.multitype">一个值也可有多种类型</link>,
-		  对于一个值可能同时存在哈希表和序列这两种类型,这时,
-		  该变量就支持索引和名称两种访问方式。
-		  不过容器基本是当作哈希表或者序列来使用的,而不是两者同时使用。</para>
-
-          <para>尽管存储在哈希表,序列(集合)中的变量可以是任意类型的,
-		  这些变量也可以是哈希表,序列(或集合)。这样就可以构建任意深度的数据结构。</para>
-
-          <para>数据模型本身(最好说成是它的根root)也是哈希表。</para>
-        </section>
-
-        <section>
-          <title>子程序</title>
-
-          <section xml:id="dgui_datamodel_method">
-            <title>方法和函数</title>
-
-            <anchor xml:id="topic.designer.methodVariable"/>
-
-            <indexterm>
-              <primary>method</primary>
-
-              <secondary>FTL 值类型</secondary>
-            </indexterm>
-
-            <para>当一个值是方法或函数的时候,那么它就可以计算其他值,结果取决于传递给它的参数。</para>
-
-            <para><phrase role="forProgrammers">这部分是对程序员来说的:方法/函数是一等类型值,
-			就像函数化的编程语言。也就是说函数/方法也可以是其他函数/方法的参数或者返回值,
-			并可以把它们定义成变量等。</phrase></para>
-
-            <para>假设程序员在数据模型中放置了一个方法变量 <literal>avg</literal>,
-			该变量用来计算数字的平均值。如果给定3和5作为参数,访问 
-			<literal>avg</literal> 时就能得到结果4。</para>
-
-            <para>方法的使用将会在 <link 
-			linkend="dgui_template_exp_methodcall">后续章节</link> 中进行解释,
-			下面这个示例会帮助我们理解方法的使用:</para>
-
-            <programlisting role="template">The average of 3 and 5 is: ${avg(3, 5)}
-The average of 6 and 10 and 20 is: ${avg(6, 10, 20)}
-The average of the price of a python and an elephant is:
-${avg(animals.python.price, animals.elephant.price)}</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">The average of 3 and 5 is: 4
-The average of 6 and 10 and 20 is: 12
-The average of the price of a python and an elephant is:
-4999.5</programlisting>
-
-            <para>那么方法和函数有什么区别呢?这是模板作者所关心的,
-			它们没有关系,但也不是一点关系都没有。
-			方法是来自于数据模型 (<phrase 
-			role="forProgrammers">它们反射了Java对象的方法</phrase>)
-			而函数是定义在模板内的 (使用 <link 
-			linkend="ref.directive.function"><literal>function</literal> 
-			指令</link> -- 也是高级话题),但二者可以用同一种方式来使用。</para>
-          </section>
-
-          <section xml:id="dgui_datamodel_userdefdir">
-            <title>用户自定义指令</title>
-
-            <indexterm>
-              <primary>macro</primary>
-
-              <secondary>FTL 值类型</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>directive</primary>
-
-              <secondary>FTL 值类型</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>user-defined directive</primary>
-
-              <secondary>FTL 值类型</secondary>
-            </indexterm>
-
-            <para>这种类型的值可以作为用户自定义指令(换句话说,就是FreeMarker的标签)
-			用户自定义指令是一种子程序,一种可以复用的模板代码段。但这也是一个高级话题,
-			将会在 <link linkend="dgui_misc_userdefdir">后续章节</link> 中进行解释。</para>
-
-            <para><phrase role="forProgrammers">这部分是对程序员来说的:
-			用户自定义指令(比如宏)也是一等值类型,就像函数/方法一样。</phrase></para>
-
-            <para>这里仅仅对用户自定义指令有一个认识即可(如果现在还不能理解可以先忽略它)。
-			假设现在有一个变量 <literal>box</literal>,它的值是用户自定义的指令,
-			用来打印一些特定的HTML信息,包含标题和一条信息。那么,
-			<literal>box</literal> 变量就可以在模板中使用(示例如下):</para>
-
-            <programlisting role="template">&lt;@<emphasis>box</emphasis> title="Attention!"&gt;
-  Too much copy-pasting may leads to
-  maintenance headaches.
-&lt;/@<emphasis>box</emphasis>&gt;</programlisting>
-          </section>
-
-          <section>
-            <title>函数/方法和用户自定义指令的比较</title>
-
-            <para>这部分内容也是对高级用户来说的(如果还不能理解可以先忽略它)。
-			如果要使用函数/方法或自定义指令去实现一些东西的时候,
-			二者之间的选择是两难的。按经验来说,如果能够实现需求,
-			请先用自定义指令而不要用函数/方法。如果:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>... 输出(返回值)的是标记(HTML,XML等)。
-				主要原因是函数的返回结果可以自动进行XML转义(这是因为
-                <literal>${<replaceable>...</replaceable>}</literal> 的特性),
-				而用户自定义指令的输出则不是
-				(这是因为 <literal>&lt;@<replaceable>...</replaceable>&gt;</literal> 的特性所致;
-				它的输出假定是标记,因此已经转义过了)。</para>
-              </listitem>
-
-              <listitem>
-                <para>... 副作用也是很重要的一点,它没有返回值。
-				例如一个指令的目的是往服务器日志中添加一条。
-				(事实上不能得到自定义指令的返回值,
-				但有些反馈的类型是有可能设置非本地变量的。)</para>
-              </listitem>
-
-              <listitem>
-                <para>... 会进行流程的控制(就像 <literal>list</literal> 
-				或 <literal>if</literal> 指令那样)。但是不能在函数/方法上这么做。</para>
-              </listitem>
-            </itemizedlist>
-
-            <para>在模板中,FreeMarker不知道的Java对象的方法通常是可以作为方法来使用的,
-			而不用考虑Java对象方法本身的特性,因为在这里没有其他的选择。</para>
-          </section>
-        </section>
-
-        <section>
-          <title>其它</title>
-
-          <section xml:id="dgui_datamodel_node">
-            <title>结点</title>
-
-            <indexterm>
-              <primary>node</primary>
-
-              <secondary>FTL 值类型</secondary>
-            </indexterm>
-
-            <para>结点变量代表了树状结构中的一个结点,而且通常是配合 
-			<link linkend="xgui">XML 处理</link>的,这是专业而且更高级的话题。</para>
-
-            <para>这里我们仅对 <emphasis>高级用户</emphasis> 进行一个概要说明:
-			结点和存储在其他结点中的序列很相似,通常也被当作为子结点。结点存储它所在的容器结点的引用,
-			也就是父结点。结点的主要作用是拓扑信息;其它数据必须通过使用多类型的值来存储。
-			就像一个值可以同时是一个结点和一个数字,这样它存储的数字可以作为如支付额来使用。
-			除了拓扑信息,结点也可以存储一些元信息(即metadata,译者注):如结点名称,它的类型(字符串), 
-			命名空间(字符串)。若一个结点象征XHTML文档中的 <literal>h1</literal> 元素,
-			那么它的名字可以是 <literal>"h1"</literal>,类型可以是 <literal>"element"</literal>,
-			命名空间可以是 <literal>"http://www.w3.org/1999/xhtml"</literal>。但对于数据模型设计者来说,
-			这些元信息,还有如何来使用它们又有什么意义呢。检索拓扑信息和元信息的方法将会在 
-			<link linkend="ref_builtins_node">后续章节</link> 中来说明(这里可以先不用理解它们)。</para>
-          </section>
-        </section>
-      </section>
-    </chapter>
-
-    <chapter xml:id="dgui_template">
-      <title>模板</title>
-
-      <indexterm>
-        <primary>template</primary>
-      </indexterm>
-
-      <note>
-        <para>这里假设你已经阅读完 <xref linkend="dgui_quickstart"/> 
-		和 <xref linkend="dgui_datamodel"/> 章节了。</para>
-      </note>
-
-      <section xml:id="dgui_template_overallstructure">
-        <title>总体结构</title>
-
-        <para>实际上用程序语言编写的程序就是模板。
-        <indexterm>
-            <primary>FTL</primary>
-          </indexterm><emphasis role="term">FTL</emphasis> (代表FreeMarker模板语言)。
-		  这是为编写模板设计的非常简单的编程语言。</para>
-
-        <para>模板(FTL编程)是由如下部分混合而成的:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para><emphasis role="term">文本</emphasis><indexterm>
-                <primary>text</primary>
-              </indexterm>:文本会照着原样来输出。</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">插值</emphasis><indexterm>
-                <primary>interpolation</primary>
-              </indexterm>:这部分的输出会被计算的值来替换。插值由 
-            <literal>${</literal> and <literal>}</literal> 所分隔(或者
-            <literal>#{</literal> and <literal>}</literal>,这种风格已经不建议再使用了;<link
-            linkend="ref_depr_numerical_interpolation">点击查看更多</link>)。</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">FTL 标签</emphasis><indexterm>
-                <primary>FTL tag</primary>
-              </indexterm>:FTL标签和HTML标签很相似,但是它们却是给FreeMarker的指示,
-			  而且不会打印在输出内容中。</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">注释</emphasis><indexterm>
-                <primary>comment</primary>
-              </indexterm><indexterm>
-                <primary>&lt;#--...--&gt;</primary>
-              </indexterm><indexterm>
-                <primary>#</primary>
-              </indexterm>:注释和HTML的注释也很相似,但它们是由 
-			  <literal>&lt;#--</literal> 和
-            <literal>--&gt;</literal>来分隔的。注释会被FreeMarker直接忽略,
-			更不会在输出内容中显示。</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>我们来看一个具体的模板。其中的内容已经用颜色来标记了: 
-		<phrase role="markedText">文本</phrase>,
-        <phrase role="markedInterpolation">插值</phrase>, <phrase
-        role="markedFTLTag">FTL 标签</phrase>, <phrase
-        role="markedComment">注释</phrase>。为了看到可见的 
-		<link linkend="gloss.lineBreak">换行符</link>,
-		这里使用了 <phrase role="markedInvisibleText">[BR]</phrase>。</para>
-
-        <programlisting role="template"><phrase role="markedText">&lt;html&gt;<phrase
-              role="markedInvisibleText">[BR]</phrase>
-&lt;head&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-  &lt;title&gt;Welcome!&lt;/title&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;/head&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;body&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedComment">&lt;#-- Greet the user with his/her name --&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  &lt;h1&gt;Welcome <phrase role="markedInterpolation">${user}</phrase>!&lt;/h1&gt;<phrase
-              role="markedInvisibleText">[BR]</phrase>
-  &lt;p&gt;We have these animals:<phrase role="markedInvisibleText">[BR]</phrase>
-  &lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedFTLTag">&lt;#list animals as animal&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-    &lt;li&gt;<phrase role="markedInterpolation">${animal.name}</phrase> for <phrase
-              role="markedInterpolation">${animal.price}</phrase> Euros<phrase
-              role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedFTLTag">&lt;/#list&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  &lt;/ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;/body&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;/html&gt;</phrase></programlisting>
-
-        <para>FTL是区分大小写的。 <literal>list</literal> 是指令的名称而 
-		<literal>List</literal> 就不是。类似地 <literal>${name}</literal> 
-		和 <literal>${Name}</literal> 或 <literal>${NAME}</literal> 也是不同的。</para>
-
-        <para>请注意非常重要的一点: <phrase role="markedInterpolation">插值</phrase> 
-		仅仅可以在 <phrase role="markedText">文本</phrase> 中使用。
-		(也可以是字符串表达式;请参考 
-		<link linkend="dgui_template_exp_stringop_interpolation">后续内容</link>)</para>
-
-        <para><phrase role="markedFTLTag">FTL 标签</phrase> 不可以在其他
-		<phrase role="markedFTLTag">FTL 标签</phrase> 
-		和 <phrase role="markedInterpolation">插值</phrase>中使用。比如,
-		这样做是 <emphasis>错误</emphasis> 的: 
-		<literal>&lt;#if &lt;#include 'foo'&gt;='bar'&gt;...&lt;/#if&gt;</literal></para>
-
-        <para><phrase role="markedComment">注释</phrase> 可以放在
-		<phrase role="markedFTLTag">FTL 标签</phrase> 
-		和 <phrase role="markedInterpolation">插值</phrase>中。比如:</para>
-
-        <programlisting role="template"><phrase role="markedText">&lt;h1&gt;Welcome <phrase
-              role="markedInterpolation">${user <phrase role="markedComment">&lt;#-- The name of user --&gt;</phrase>}</phrase>!&lt;/h1&gt;<phrase
-              role="markedInvisibleText">[BR]</phrase>
-&lt;p&gt;We have these animals:<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedFTLTag">&lt;#list <phrase role="markedComment">&lt;#-- some comment... --&gt;</phrase> animals as <phrase
-                role="markedComment">&lt;#-- again... --&gt;</phrase> animal&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase></phrase>
-<replaceable>...</replaceable></programlisting>
-
-        <note>
-          <para>如果您已经自行尝试测试上面所有示例的话:那么也许会注意到,一些空格、
-		  制表符和换行符从模板的输出中都不见了,尽管我们之前已经说了 
-		  <phrase role="markedText">文本</phrase> 是按照原样输出的。
-		  现在不用为此而计较,这是由于FreeMarker的"空格剥离"特性在起作用,
-		  它当然会自动去除一些多余的空格,制表符和换行符了。
-		  这个特性在 <link linkend="dgui_misc_whitespace">后续内容</link> 中会解释到。</para>
-        </note>
-      </section>
-
-      <section xml:id="dgui_template_directives">
-        <title>指令</title>
-
-        <indexterm>
-          <primary>&lt;#...&gt;</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>#</primary>
-        </indexterm>
-
-        <anchor xml:id="term.designer.directive"/>
-
-        <remark>请注意,表达式章节是基于本章之上的,而插值章节是基于表达式章节的。
-		因此,指令指令章节就是基本内容后的第一部分内容。</remark>
-
-        <para><indexterm>
-            <primary>directive</primary>
-          </indexterm>使用 FTL标签来调用 <emphasis role="term">指令</emphasis>。
-		  在示例中已经调用了 <literal>list</literal> 指令。在语法上我们使用了两个标签:
-		  <literal>&lt;#list animals as animal&gt;</literal> 
-		  和 <literal>&lt;/#list&gt;</literal>。</para>
-
-        <para><indexterm>
-            <primary>FTL tag</primary>
-          </indexterm>FTL 标签分为两种:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>开始标签:
-            <literal>&lt;#<replaceable>directivename</replaceable>
-            <replaceable>parameters</replaceable>&gt;</literal></para>
-          </listitem>
-
-          <listitem>
-            <para>结束标签:
-            <literal>&lt;/#<replaceable>directivename</replaceable>&gt;</literal></para>
-          </listitem>
-        </itemizedlist>
-
-        <para>除了标签以 <literal>#</literal> 开头外,其他都和HTML,XML的语法很相似。
-		如果标签没有嵌套内容(在开始标签和结束标签之间的内容),那么可以只使用开始标签。
-		例如 <literal>&lt;#if
-        <replaceable>something</replaceable>&gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal>,
-        而FreeMarker知道 <literal>&lt;#include <replaceable>something</replaceable>&gt;</literal> 中的
-		<literal>include</literal> 指令没有可嵌套的内容。</para>
-
-        <para><literal><replaceable>parameters</replaceable></literal> 的格式由
-        <literal><replaceable>directivename</replaceable></literal>来决定。</para>
-
-        <para>事实上,指令有两种类型: <link 
-		linkend="gloss.predefinedDirective">预定义指令</link> 
-		和 <link linkend="gloss.userDefinedDirective">用户自定义指令</link>。
-		对于用户自定义的指令使用 <literal>@</literal> 来代替 
-		<literal>#</literal>,比如,<literal>&lt;@mydirective 
-		<replaceable>parameters</replaceable>&gt;<replaceable>...</replaceable>&lt;/@mydirective&gt;</literal>。
-		更深的区别在于如果指令没有嵌套内容,那么必须这么使用 <literal>&lt;@mydirective
-        <replaceable>parameters</replaceable> /&gt;</literal>,这和XML语法很相似
-		(例如 <literal>&lt;img <replaceable>...</replaceable> /&gt;</literal>)。
-		但用户自定义指令是更高级的话题,将会在 <link
-        linkend="dgui_misc_userdefdir">后续章节</link> 中继续讨论。</para>
-
-        <para>像HTML标签一样,FTL标签也必须正确地嵌套使用。下面这段示例代码就是错的,
-		因为 <literal>if</literal> 指令在 <literal>list</literal> 指令嵌套内容的内外都有:</para>
-
-        <programlisting role="template">&lt;ul&gt;
-<emphasis>&lt;#list animals as animal&gt;</emphasis>
-  &lt;li&gt;${animal.name} for ${animal.price} Euros
-  <emphasis>&lt;#if user == "Big Joe"&gt;</emphasis>
-     (except for you)
-<emphasis>&lt;/#list&gt;</emphasis> &lt;#-- WRONG! The "if" has to be closed first. --&gt;
-<emphasis>&lt;/#if&gt;</emphasis>
-&lt;/ul&gt;</programlisting>
-
-        <para>请注意,FreeMarker 仅仅关心FTL标签的嵌套而不关心HTML标签的嵌套。
-		它只会把HTML看做是文本,不会来解释HTML。</para>
-
-        <para>如果你尝试使用一个不存在的指令(比如,输错了指令的名称),
-		FreeMarker 就会拒绝执行模板,同时抛出错误信息。</para>
-
-        <para>FreeMarker会忽略FTL标签中多余的 <link 
-		linkend="gloss.whiteSpace">空白标记</link>,所以也可以这么来写代码:</para>
-
-        <programlisting role="template"><phrase role="markedText"><phrase
-              role="markedFTLTag">&lt;#list<phrase role="markedInvisibleText">[BR]</phrase>
-  animals       as<phrase role="markedInvisibleText">[BR]</phrase>
-     animal<phrase role="markedInvisibleText">[BR]</phrase>
-&gt;</phrase><phrase role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedInterpolation">${animal.name}</phrase> for <phrase
-              role="markedInterpolation">${animal.price}</phrase> Euros<phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedFTLTag">&lt;/#list    &gt;</phrase></phrase></programlisting>
-
-        <para>当然,也不能在 <literal>&lt;</literal>,<literal>&lt;/</literal> 
-		和指令名中间入空白标记。</para>
-
-        <para>所有指令的详细介绍可以在 <xref linkend="ref_directives"/> 
-		中找到(但是建议您先看表达式章节)。</para>
-
-        <note>
-          <para>通过配置,FreeMarker 可以在FTL标签和FTL注释中,
-		  使用 <literal>[</literal> 和 <literal>]</literal> 来代替
-		  <literal>&lt;</literal> 和 <literal>&gt;</literal>,就像
-          <literal>[#if user == "Big Joe"]<replaceable>...</replaceable>[/#if]</literal>。
-		  要获取更多信息,请参考:<xref linkend="dgui_misc_alternativesyntax"/>。</para>
-        </note>
-
-        <note>
-          <para>通过配置,FreeMarker 可以不需要 <literal>#</literal> 
-		  来理解预定义指令(比如 <literal>&lt;if user
-          == "Big Joe"&gt;<replaceable>...</replaceable>&lt;/if&gt;</literal>)。
-		  而我们不建议这样来使用。要获取更多信息,请参考:<xref linkend="ref_depr_oldsyntax"/>。</para>
-        </note>
-      </section>
-
-      <section xml:id="dgui_template_exp">
-        <title>表达式</title>
-
-        <para><indexterm>
-            <primary>expression</primary>
-          </indexterm>当需要给插值或者指令参数提供值时,可以使用变量或其他复杂的表达式。
-		  例如,我们设x为8,y为5,那么 <literal>(x + y)/2</literal> 
-		  的值就会被处理成数字类型的值6.5。</para>
-
-        <para>在我们展开细节之前,先来看一些具体的例子:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>当给插值提供值时:插值的使用方式为 
-			<literal>${<replaceable>expression</replaceable>}</literal>,
-			把它放到你想输出文本的位置上,然后给值就可以打印出来了。
-			即 <literal>${(5 + 8)/2}</literal> 会打印出 ''6.5'' 来
-			(如果输出的语言不是美国英语,也可能打印出''6,5''来)。</para>
-          </listitem>
-
-          <listitem>
-            <para>当给指令参数提供值时:在入门章节我们已经看到 
-			<literal>if</literal> 指令的使用了。这个指令的语法是:<literal>&lt;#if 
-			<replaceable>expression</replaceable>&gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal>。
-            这里的表达式计算结果必须是布尔类型的。比如 
-			<literal>&lt;#if 2 &lt; 3&gt;</literal> 中的 <literal>2 
-			&lt;3</literal> (2小于3)是结果为 <literal>true</literal> 的布尔表达式。</para>
-          </listitem>
-        </itemizedlist>
-
-        <section xml:id="exp_cheatsheet">
-          <title>快速浏览(备忘单)</title>
-
-          <para>这里给已经了解 FreeMarker 的人或有经验的程序员的提个醒:</para>
-
-          <itemizedlist spacing="compact">
-            <listitem>
-              <para><link linkend="dgui_template_exp_direct">直接指定值</link></para>
-
-              <itemizedlist spacing="compact">
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_direct_string">字符串</link>:
-                  <literal>"Foo"</literal> 或者 <literal>'Foo'</literal> 或者
-                  <literal>"It's \"quoted\""</literal> 或者 <literal>'It\'s
-                  "quoted"'</literal> 或者
-                  <literal>r"C:\raw\string"</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_direct_number">数字</link>:
-                  <literal>123.45</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_direct_boolean">布尔值</link>:
-                  <literal>true</literal>, <literal>false</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_direct_seuqence">序列</link>:
-                  <literal>["foo", "bar", 123.45]</literal>; 值域:
-                  <literal>0..9</literal>, <literal>0..&lt;10</literal> (或
-                  <literal>0..!10</literal>), <literal>0..</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_direct_hash">哈希表</link>:
-                  <literal>{"name":"green mouse",
-                  "price":150}</literal></para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_var">检索变量</link></para>
-
-              <itemizedlist spacing="compact">
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_var_toplevel">顶层变量</link>:
-				  <literal>user</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link linkend="dgui_template_exp_var_hash">从哈希表中检索数据</link>: <literal>user.name</literal>,
-                  <literal>user["name"]</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_var_sequence">从序列中检索数据</link>:
-                  <literal>products[5]</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link linkend="dgui_template_exp_var_special">特殊变量</link>: <literal>.main</literal></para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_stringop">字符串操作</link></para>
-
-              <itemizedlist spacing="compact">
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_stringop_interpolation">插值(或连接)</link>:
-                  <literal>"Hello ${user}!"</literal> (或 <literal>"Hello
-                  " + user + "!"</literal>)</para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_get_character">获取一个字符</link>:
-				  <literal>name[0]</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_stringop_slice">字符串切分:</link> 包含结尾:
-				  <literal>name[0..4]</literal>,不包含结尾:
-				  <literal>name[0..&lt;5]</literal>,基于长度(宽容处理):
-				  <literal>name[0..*5]</literal>,去除开头:
-                  <literal>name[5..]</literal></para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_sequenceop">序列操作</link></para>
-
-              <itemizedlist spacing="compact">
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_sequenceop_cat">连接</link>:
-                  <literal>users + ["guest"]</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_seqenceop_slice">序列切分</link>:包含结尾:
-                  <literal>products[20..29]</literal>, 不包含结尾:
-                  <literal>products[20..&lt;30]</literal>,基于长度(宽容处理):
-                  <literal>products[20..*10]</literal>,去除开头:
-                  <literal>products[20..]</literal></para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_hashop">哈希表操作</link></para>
-
-              <itemizedlist spacing="compact">
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_hashop_cat">连接</link>:
-                  <literal>passwords + { "joe": "secret42" }</literal></para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_arit">算术运算</link>:
-			  <literal>(x * 1.5 + 10) / 2 - y %
-              100</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><link
-              linkend="dgui_template_exp_comparison">比较运算</link>:
-              <literal>x == y</literal>, <literal>x != y</literal>,
-              <literal>x &lt; y</literal>, <literal>x &gt; y</literal>,
-              <literal>x &gt;= y</literal>, <literal>x &lt;= y</literal>,
-              <literal>x lt y</literal>, <literal>x lte y</literal>,
-              <literal>x gt y</literal>, <literal>x gte y</literal>,
-              等等。。。。。。</para>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_logicalop">逻辑操作</link>:
-			  <literal>!registered &amp;&amp; (firstVisit
-              || fromEurope)</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><link
-              linkend="dgui_template_exp_builtin">内建函数</link>:
-              <literal>name?upper_case</literal>,
-              <literal>path?ensure_starts_with('/')</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_methodcall">方法调用</link>:
-			  <literal>repeat("What", 3)</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_missing">处理不存在的值</link>:</para>
-
-              <itemizedlist spacing="compact">
-                <listitem>
-                  <para><link
-                  linkend="dgui_template_exp_missing_default">默认值</link>:
-				  <literal>name!"unknown"</literal> 或者
-                  <literal>(user.name)!"unknown"</literal> 或者
-                  <literal>name!</literal> 或者
-                  <literal>(user.name)!</literal></para>
-                </listitem>
-
-                <listitem>
-                  <para><link linkend="dgui_template_exp_missing_test">检测不存在的值</link>: <literal>name??</literal> 或者
-                  <literal>(user.name)??</literal></para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para><link linkend="dgui_template_exp_assignment">赋值操作</link>:
-			  <literal>=</literal>, <literal>+=</literal>,
-              <literal>-=</literal>, <literal>*=</literal>,
-              <literal>/=</literal>, <literal>%=</literal>,
-              <literal>++</literal>, <literal>--</literal></para>
-            </listitem>
-          </itemizedlist>
-
-          <para>请参考: <link
-          linkend="dgui_template_exp_precedence">运算符优先级</link></para>
-        </section>
-
-        <section xml:id="dgui_template_exp_direct">
-          <title>直接确定值</title>
-
-          <indexterm>
-            <primary>literal</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>constant</primary>
-          </indexterm>
-
-          <para>通常我们喜欢是使用直接确定的值而不是计算的结果。</para>
-
-          <section xml:id="dgui_template_exp_direct_string">
-            <title>字符串</title>
-
-            <indexterm>
-              <primary>string</primary>
-
-              <secondary>literal</secondary>
-            </indexterm>
-
-            <para>在文本中确定字符串值的方法是看双引号,比如:
-			<literal>"some text"</literal>,或单引号,比如:
-			<literal>'some text'</literal>。这两种形式是等同的。
-			如果文本自身包含用于字符引用的引号
-			( <literal>"</literal> 或 <literal>'</literal>)或反斜杠时,
-			应该在它们的前面再加一个反斜杠;这就是转义。
-			转义允许直接在文本中输入任何字符,
-			也包括<link linkend="gloss.lineBreak">换行</link>。例如:</para>
-
-            <programlisting role="template">${"It's \"quoted\" and
-this is a backslash: \\"}
-
-${'It\'s "quoted" and
-this is a backslash: \\'}</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">It's "quoted" and
-this is a backslash: \
-
-It's "quoted" and
-this is a backslash: \</programlisting>
-
-            <note>
-              <para>这里当然可以直接在模板中输入文本而不需要 
-			  <literal>${<replaceable>...</replaceable>}</literal>。
-			  但是我们在这里用它只是为了示例来说明表达式的使用。</para>
-            </note>
-
-            <anchor xml:id="topic.escapeSequence"/>
-
-            <indexterm>
-              <primary>escape sequences</primary>
-            </indexterm>
-
-            <para>下面的表格是FreeMarker支持的所有转义字符。
-			在字符串使用反斜杠的其他所有情况都是错误的,运行这样的模板都会失败。</para>
-
-            <informaltable border="1">
-              <thead>
-                <tr>
-                  <th>转义序列</th>
-
-                  <th>含义</th>
-                </tr>
-              </thead>
-
-              <tbody>
-                <tr>
-                  <td><literal>\"</literal></td>
-
-                  <td>引号 (u0022)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\'</literal></td>
-
-                  <td>单引号(又称为撇号) (u0027)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\{</literal></td>
-
-                  <td>起始花括号:<literal>{</literal></td>
-                </tr>
-
-                <tr>
-                  <td><literal>\\</literal></td>
-
-                  <td>反斜杠 (u005C)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\n</literal></td>
-
-                  <td>换行符 (u000A)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\r</literal></td>
-
-                  <td>回车 (u000D)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\t</literal></td>
-
-                  <td>水平制表符(又称为tab) (u0009)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\b</literal></td>
-
-                  <td>退格 (u0008)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\f</literal></td>
-
-                  <td>换页 (u000C)</td>
-                </tr>
-
-                <tr>
-                  <td><literal>\l</literal></td>
-
-                  <td>小于号:<literal>&lt;</literal></td>
-                </tr>
-
-                <tr>
-                  <td><literal>\g</literal></td>
-
-                  <td>大于号:<literal>&gt;</literal></td>
-                </tr>
-
-                <tr>
-                  <td><literal>\a</literal></td>
-
-                  <td>&amp;符:<literal>&amp;</literal></td>
-                </tr>
-
-                <tr>
-                  <td><literal>\x<replaceable>Code</replaceable></literal></td>
-
-                  <td>字符的16进制 <link linkend="gloss.unicode">Unicode</link> 码 (<link
-                  linkend="gloss.UCS">UCS</link> 码)</td>
-                </tr>
-              </tbody>
-            </informaltable>
-
-            <para>在 <literal>\x</literal> 之后的 
-			<literal><replaceable>Code</replaceable></literal> 
-			是1-4位的16进制码。下面这个示例中都是在字符串中放置版权符号:
-            <literal>"\xA9 1999-2001"</literal>,
-            <literal>"\x0A9 1999-2001"</literal>,
-            <literal>"\x00A9 1999-2001"</literal>。
-			如果紧跟16进制码后一位的字符也能解释成16进制码时,
-			就必须把4位补全,否则FreeMarker就会误解你的意图。</para>
-
-            <para>请注意,字符序列 <literal>${</literal> (和 <literal>#{</literal>) 
-			有特殊的含义,它们被用做插入表达式的数值(典型的应用是变量的值:
-			<literal>"Hello ${user}!"</literal>)。这将在 <link 
-			linkend="dgui_template_exp_stringop_interpolation">后续章节</link>中解释。
-			如果想要打印 <literal>${</literal> 或 <literal>#{</literal>,
-			就要使用下面所说的原生字符串,或者进行转义。就像 
-			<literal>"foo $\{bar}"</literal>中的 <literal>{</literal>。</para>
-
-            <indexterm>
-              <primary>raw string literal</primary>
-            </indexterm>
-
-            <para>原生字符串是一种特殊的字符串。在原生字符串中,
-			反斜杠和 <literal>${</literal> 没有特殊含义,
-			它们被视为普通的字符。为了表明字符串是原生字符串,
-			在开始的引号或单引号之前放置字母<literal>r</literal>,例如:</para>
-
-            <programlisting role="template">${r"${foo}"}
-${r"C:\foo\bar"}</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">${foo}
-C:\foo\bar</programlisting>
-          </section>
-
-          <section xml:id="dgui_template_exp_direct_number">
-            <title>数字</title>
-
-            <indexterm>
-              <primary>number</primary>
-
-              <secondary>literal</secondary>
-            </indexterm>
-
-            <para>输入不带引号的数字就可以直接指定一个数字,
-			必须使用点作为小数的分隔符而不能是其他的分组分隔符。
-			可以使用 <literal>-</literal> 或 <literal>+</literal> 
-			来表明符号 (<literal>+</literal> 是多余的)。
-			科学记数法暂不支持使用 (<literal>1E3</literal> 就是错误的),
-			而且也不能在小数点之前不写0(<literal>.5</literal> 也是错误的)。</para>
-
-            <para>下面的数字都是合法的:<literal>0.08</literal>,
-            <literal>-5.013</literal>,<literal>8</literal>,
-            <literal>008</literal>,<literal>11</literal>,
-            <literal>+11</literal></para>
-
-            <para>请注意,像 <literal>08</literal>、
-            <literal>+8</literal>、 <literal>8.00</literal> 和
-            <literal>8</literal> 这样的数值是完全等同的,它们都是数字8。
-			所以, <literal>${08}</literal>、<literal>${+8}</literal>、 
-			<literal>${8.00}</literal> 和 <literal>${8}</literal> 
-			的输出都是一样的。</para>
-          </section>
-
-          <section xml:id="dgui_template_exp_direct_boolean">
-            <title>布尔值</title>
-
-            <indexterm>
-              <primary>boolean</primary>
-
-              <secondary>literal</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>literal</primary>
-
-              <secondary>boolean</secondary>
-            </indexterm>
-
-            <para>直接写 <literal>true</literal> 或者 
-			<literal>false</literal> 就表示一个布尔值了,不需使用引号。</para>
-          </section>
-
-          <section xml:id="dgui_template_exp_direct_seuqence">
-            <title>序列</title>
-
-            <indexterm>
-              <primary>sequence</primary>
-
-              <secondary>literal</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>numerical sequence</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>numerical range expression</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>range expression</primary>
-            </indexterm>
-
-            <para>指定一个文字的序列,使用逗号来分隔其中的每个 <link 
-			linkend="topic.dataModel.subVar">子变量</link>,
-			然后把整个列表放到方括号中。例如:</para>
-
-            <programlisting role="template">&lt;#list <emphasis>["foo", "bar", "baz"]</emphasis> as x&gt;
-${x}
-&lt;/#list&gt;</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">foo
-bar
-baz
- </programlisting>
-
-            <para>列表中的项目是表达式,那么也可以这样做: 
-			<literal>[2 + 2, [1, 2, 3, 4], "foo"]</literal>。
-			其中第一个子变量是数字4,第二个子变量是一个序列,
-			第三个子变量是字符串"foo"。</para>
-          </section>
-
-          <section xml:id="dgui_template_exp_direct_ranges">
-            <title>值域</title>
-
-            <para>值域也是序列,但它们由指定包含的数字范围所创建,
-			而不需指定序列中每一项。比如:
-            <literal>0..&lt;m</literal>,这里假定 <literal>m</literal> 
-			变量的值是5,那么这个序列就包含  
-			<literal>[0, 1, 2, 3, 4]</literal>。值域的主要作用有:使用
-			<literal>&lt;#list<replaceable>...</replaceable>&gt;</literal>
-			来迭代一定范围内的数字,<link 
-			linkend="dgui_template_exp_seqenceop_slice">序列切分</link> 和 
-			<link linkend="dgui_template_exp_stringop_slice">字符串切分</link>。</para>
-
-            <para>值域表达式的通用形式是(
-            <literal><replaceable>start</replaceable></literal> 和
-            <literal><replaceable>end</replaceable></literal> 
-			可以是任意的结果为数字表达式):</para>
-
-            <itemizedlist>
-              <listitem>
-                <para><literal><replaceable>start</replaceable>..<replaceable>end</replaceable></literal>:
-                包含结尾的值域。比如 <literal>1..4</literal> 就是 
-				<literal>[1, 2, 3, 4]</literal>, 而 <literal>4..1</literal> 
-				就是 <literal>[4, 3, 2, 1]</literal>。当心一点,
-				包含结尾的值域不会是一个空序列,所以 <literal>0..length-1</literal> 
-				就是 <emphasis>错误的</emphasis>,因为当长度是 <literal>0</literal> 时,
-				序列就成了 <literal>[0, -1]</literal>。</para>
-              </listitem>
-
-              <listitem>
-                <para><literal><replaceable>start</replaceable>..&lt;<replaceable>end</replaceable></literal>
-                或
-                <literal><replaceable>start</replaceable>..!<replaceable>end</replaceable></literal>:
-				不包含结尾的值域。比如 <literal>1..&lt;4</literal> 就是 
-				<literal>[1, 2, 3]</literal>,<literal>4..&lt;1</literal> 
-				就是 <literal>[4, 3, 2]</literal>, 而 <literal>1..&lt;1</literal> 
-				表示 <literal>[]</literal>。请注意最后一个示例;
-				结果可以是空序列,和  <literal>..&lt;</literal> 
-				和 <literal>..!</literal> 没有区别; 最后这种形式在应用程序中使用了 
-				<literal>&lt;</literal> 字符而引发问题(如HTML编辑器等)。</para>
-              </listitem>
-
-              <listitem>
-                <para><literal><replaceable>start</replaceable>..*<replaceable>length</replaceable></literal>:
-                限定长度的值域,比如 <literal>10..*4</literal> 就是 
-				<literal>[10, 11, 12, 13]</literal>,<literal>10..*-4</literal> 
-				就是 <literal>[10, 9, 8, 7]</literal>,而 <literal>10..*0</literal> 
-				表示 <literal>[]</literal>。当这些值域被用来切分时,
-				如果切分后的序列或者字符串结尾在指定值域长度之前,则切分不会有问题;请参考 
-				<link linkend="dgui_template_exp_seqenceop_slice">序列切分</link> 来获取更多信息。</para>
-
-                <note>
-                  <para>限定长度的值域是在 FreeMarker 2.3.21版本中引入的。</para>
-                </note>
-              </listitem>
-
-              <listitem>
-                <para><literal><replaceable>start</replaceable>..</literal>:
-				无右边界值域。这和限制长度的值域很像,只是长度是无限的。
-				比如 <literal>1..</literal> 就是
-                <literal>[1, 2, 3, 4, 5, 6, ... ]</literal>,直到无穷大。
-				但是处理(比如列表显示)这种值域时要万分小心,处理所有项时,
-				会花费很长时间,直到内存溢出应用程序崩溃。
-				和限定长度的值域一样,当它们被切分时,
-				遇到切分后的序列或字符串结尾时,切分就结束了。</para>
-
-                <warning>
-                  <para>无右边界值域在 FreeMarker 2.3.21 版本以前只能用于切分,
-				  若用于其它用途,它就像空序列一样了。要使用新的特性,
-				  使用 FreeMarker 2.3.21 版本是不够的,程序员要设置 
-				  <literal>incompatible_improvements</literal> 至少到2.3.21版本。</para>
-                </warning>
-              </listitem>
-            </itemizedlist>
-
-            <para>值域的进一步注意事项:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>值域表达式本身并没有方括号,比如这样编写代码 
-				<literal>&lt;#assign myRange = 0..&lt;x&gt;</literal>,
-				而不是 <literal>&lt;#assign myRange = [0..&lt;x]&gt;</literal>。
-				后者会创建一个包含值域的序列。方括号是切分语法的一部分,就像 
-                <literal><replaceable>seq</replaceable>[<replaceable>myRange</replaceable>]</literal>。</para>
-              </listitem>
-
-              <listitem>
-                <para>可以在 <literal>..</literal> 的两侧编写算术表达式而不需要圆括号,
-				就像 <literal>n + 1 ..&lt; m / 2 - 1</literal>。</para>
-              </listitem>
-
-              <listitem>
-                <para><literal>..</literal>,<literal>..&lt;</literal>,
-                <literal>..!</literal> 和 <literal>..*</literal> 是运算符,
-				所以它们中间不能有空格。就像 <literal>n .. &lt;m</literal> 
-				这样是错误的,但是 <literal>n ..&lt; m</literal> 这样就可以。</para>
-              </listitem>
-
-              <listitem>
-                <para>无右边界值域的定义大小是2147483647 (如果
-                <literal>incompatible_improvements</literal> 低于2.3.21版本,那么就是0),
-				这是由于技术上的限制(32位)。但当列表显示它们的时候,实际的长度是无穷大。</para>
-              </listitem>
-
-              <listitem>
-                <para>值域并不存储它们包含的数字,那么对于 <literal>0..1</literal> 和
-                <literal>0..100000000</literal> 来说,创建速度都是一样的,
-				并且占用的内存也是一样的。</para>
-              </listitem>
-            </itemizedlist>
-          </section>
-
-          <section xml:id="dgui_template_exp_direct_hash">
-            <title>哈希表</title>
-
-            <indexterm>
-              <primary>hash</primary>
-
-              <secondary>literal</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>literal</primary>
-
-              <secondary>hash</secondary>
-            </indexterm>
-
-            <para>在模板中指定一个哈希表,就可以遍历用逗号分隔开的"键/值"对,
-			把列表放到花括号内即可。键和值成对出现并以冒号分隔。比如:
-			<literal>{ "name": "green mouse", "price": 150 }</literal>。
-			请注意名和值都是表达式,但是用来检索的名称就必须是字符串类型,
-			而值可以是任意类型。</para>
-          </section>
-        </section>
-
-        <section xml:id="dgui_template_exp_var">
-          <title>检索变量</title>
-
-          <section xml:id="dgui_template_exp_var_toplevel">
-            <title>顶层变量</title>
-
-            <indexterm>
-              <primary>subvariable</primary>
-
-              <secondary>accessing</secondary>
-            </indexterm>
-
-            <para>访问顶层的变量,可以简单地使用变量名。例如,
-			用表达式 <literal>user</literal> 就可以在根上获取以 
-			<quote>user</quote> 为名存储的变量值。然后打印出存储在里面的内容:</para>
-
-            <programlisting role="template">${user}</programlisting>
-
-            <para>如果没有顶层变量,那么 FreeMarker 在处理表达式时就会发生错误,
-			进而终止模板的执行(除非程序员事先配置了 FreeMarker)。</para>
-
-            <para>在这种表达式中,变量名只可以包含字母(也可以是非拉丁文),
-			数字(也可以是非拉丁数字),下划线 (<literal>_</literal>),
-			美元符号 (<literal>$</literal>),at符号 (<literal>@</literal>)。
-			此外,第一个字符不可以是ASCII码数字(<literal>0</literal>-<literal>9</literal>)。
-			从 FreeMarker 2.3.22 版本开始,变量名在任何位置也可以包含负号
-			(<literal>-</literal>),点(<literal>.</literal>)和冒号(<literal>:</literal>),
-			但这些必须使用前置的反斜杠(<literal>\</literal>)来转义,
-			否则它们将被解释成操作符。比如,读取名为<quote>data-id</quote>的变量,
-			表达式为 <literal>data\-id</literal>,因为 <literal>data-id</literal> 
-			将被解释成 <quote>data minus id</quote>。
-			(请注意,这些转义仅在标识符中起作用,而不是字符串中。)</para>
-          </section>
-
-          <section xml:id="dgui_template_exp_var_hash">
-            <title>从哈希表中检索数据</title>
-
-            <indexterm>
-              <primary>subvariable</primary>
-
-              <secondary>accessing</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>hash</primary>
-
-              <secondary>accessing subvariable</secondary>
-            </indexterm>
-
-            <para>如果有一个表达式的结果是哈希表,
-			那么我们可以使用点和子变量的名字得到它的值,
-			假设我们有如下的数据模型:</para>
-
-            <programlisting role="dataModel">(root)
- |
- +- book
- |   |
- |   +- title = "Breeding green mouses"
- |   |
- |   +- author
- |       |
- |       +- name = "Julia Smith"
- |       |
- |       +- info = "Biologist, 1923-1985, Canada"
- |
- +- test = "title"</programlisting>
-
-            <para>现在,就可以通过<literal>book.title</literal> 
-			来读取 <literal>title</literal>,book表达式将返回一个哈希表
-			(就像上一章中解释的那样)。按这种逻辑进一步来说,我们可以使用表达式
-			<literal>book.author.name</literal> 来读取到auther的name。</para>
-
-            <para>如果我们想指定同一个表达式的子变量,那么还有另外一种语法格式:
-            <literal>book["title"]</literal>。在方括号中可以给出任意长度字符串的表达式。
-			在上面这个数据模型示例中还可以这么来获取title: <literal>book[test]</literal>。
-			下面这些示例它们含义都是相等的: <literal>book.author.name</literal>,
-            <literal>book["author"].name</literal>,
-            <literal>book.author.["name"]</literal>,
-            <literal>book["author"]["name"]</literal>。</para>
-
-            <para>当使用点式语法时,顶层变量名的命名也有相同的限制
-			(命名时只能使用字母,数字,<literal>_</literal>,<literal>$</literal>,
-			<literal>@</literal>,但是不能使用 <literal>0</literal>-<literal>9</literal>开头,
-			同时,从2.3.22版本开始,也可以使用 <literal>\-</literal>,<literal>\.</literal> 
-			和 <literal>\:</literal>)。当使用方括号语法时,则没有这样的限制,
-			因为名称可以是任意表达式的结果。(请注意,对于FreeMarker的XML支持来说,
-			如果子变量名称是 <literal>*</literal> (星号) 
-			或者 <literal>**</literal>,那么就不要使用方括号语法。)</para>
-
-            <para>对于顶层变量来说,如果尝试访问一个不存在的变量也会引起错误导致解析执行模板中断
-			(除非程序员事先配置过FreeMarker)。</para>
-          </section>
-
-          <section xml:id="dgui_template_exp_var_sequence">
-            <title>从序列中检索数据</title>
-
-            <indexterm>
-              <primary>subvariable</primary>
-
-              <secondary>accessing</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>sequence</primary>
-
-              <secondary>accessing subvariable</secondary>
-            </indexterm>
-
-            <para>这和从哈希表中检索是相同的,但是只能使用方括号语法形式来进行,
-			而且方括号内的表达式最终必须是一个数字而不是字符串。比如,要从 
-			<link linkend="example.stdDataModel">示例数据模型</link> 中获取第一个动物的名字
-			(记住第一项数字索引是0而不是1),可以这么来写: <literal>animals[0].name</literal></para>
-          </section>
-
-          <section xml:id="dgui_template_exp_var_special">
-            <title>特殊变量</title>
-
-            <indexterm>
-              <primary>special variables</primary>
-            </indexterm>
-
-            <para>特殊变量是由FreeMarker引擎本身定义的。
-			使用它们,可以按照如下语法形式来进行:
-            <literal>.<replaceable>variable_name</replaceable></literal>。.</para>
-
-            <para>通常情况下是不需使用特殊变量,而对专业用户来说可能用到。
-			所有特殊变量的说明可以参见 <link linkend="ref_specvar">参考手册</link>。</para>
-          </section>
-        </section>
-
-        <section xml:id="dgui_template_exp_stringop">
-          <title>字符串操作</title>
-
-          <indexterm>
-            <primary>string</primary>
-
-            <secondary>operations</secondary>
-          </indexterm>
-
-          <section xml:id="dgui_template_exp_stringop_interpolation">
-            <title>插值 (或连接)</title>
-
-            <indexterm>
-              <primary>interpolation</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>concatenate strings</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>joining strings</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>string</primary>
-
-              <secondary>concatenate</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>string</primary>
-
-              <secondary>interpolation</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>adding strings</primary>
-            </indexterm>
-
-            <para>如果要在字符串中插入表达式的值,可以在字符串的文字中使用 
-			<literal>${<replaceable>...</replaceable>}</literal> 
-			(已经废弃的 <literal>#{<replaceable>...</replaceable>}</literal>)。
-            <literal>${<replaceable>...</replaceable>}</literal> 在字符串中的作用和在 
-			<link linkend="dgui_template_valueinsertion"> <phrase role="markedText">文本</phrase> 
-			区是相同的</link> (它遵守相同的 <emphasis>本地化敏感</emphasis> 的数字和日期/时间格式),
-			而不是 <link linkend="ref.directive.escape">自动转义</link>。</para>
-
-            <para>示例 (假设user是 ''Big Joe''):</para>
-
-            <programlisting role="template">&lt;#assign s = "Hello ${user}!"&gt;
-${s} &lt;#-- Just to see what the value of s is --&gt;
-</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">Hello Big Joe!</programlisting>
-
-            <warning>
-              <para>用户所犯的一个常见错误是将插值放在了不需要/不应该使用的地方。
-			  插值 <emphasis>仅</emphasis> 在 <link 
-			  linkend="dgui_template_overallstructure"><phrase 
-			  role="markedText">文本</phrase> 区</link> 中有效。(比如, 
-			  <literal>&lt;h1&gt;Hello ${name}!&lt;/h1&gt;</literal>) 还有在字符串值中 
-			  (比如, <literal>&lt;#include "/footer/${company}.html"&gt;</literal>)。
-			  典型的 <emphasis>错误</emphasis> 使用是 
-			  <literal>&lt;#if ${big}&gt;...&lt;/#if&gt;</literal>,
-			  这会导致语法错误。简单写为  
-			  <literal>&lt;#if big&gt;...&lt;/#if&gt;</literal>即可。
-			  而且, <literal>&lt;#if "${big}"&gt;...&lt;/#if&gt;</literal> 
-			  也是 <emphasis>错误的</emphasis>,
-			  因为它将参数值转换为字符串,但是  <literal>if</literal> 指令只接受布尔值,
-			  那么这将导致运行时错误。</para>
-            </warning>
-
-            <para>另外,也可以使用 <literal>+</literal> 号来达到类似的效果:</para>
-
-            <programlisting role="template">&lt;#assign s = "Hello " + user + "!"&gt;</programlisting>
-
-            <para>这样的效果和使用 <literal>${<replaceable>...</replaceable>}</literal> 是一样的。</para>
-
-            <warning>
-              <para>因为 <literal>+</literal> 和使用 
-			  <literal>${<replaceable>...</replaceable>}</literal> 
-			  的规则相同,附加的字符串受到 <literal>locale</literal>,
-              <literal>number_format</literal>,<literal>date_format</literal>, 
-			  <literal>time_format</literal>,<literal>datetime_format</literal> 和
-              <literal>boolean_format</literal> 等等设置的影响,
-			  这是对人来说的,而不是通常机器的解析。默认情况下,这会导致数字出问题,
-			  因为很多地区使用分组(千分位分隔符),那么 
-			  <literal>"someUrl?id=" + id</literal> 就可能会是 
-			  <literal>"someUrl?id=1 234"</literal>。
-			  要预防这种事情的发生,请使用 <literal>?c</literal> 
-			  (对计算机来说)内建函数,那么在 <literal>"someUrl?id=" + id?c</literal> 或
-              <literal>"someUrl?id=${id?c}"</literal>中,
-			  就会得到如 <literal>"someUrl?id=1234"</literal> 
-			  这样的输出, 而不管本地化和格式的设置是什么。</para>
-            </warning>
-          </section>
-
-          <section xml:id="dgui_template_exp_get_character">
-            <title>获取字符</title>
-
-            <indexterm>
-              <primary>charAt</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>get character</primary>
-            </indexterm>
-
-            <para>在给定索引值时可以获取字符串中的一个字符,这和 <link 
-			linkend="dgui_template_exp_var_sequence">序列的子变量</link>是相似的,
-			比如 <literal>user[0]</literal>。这个操作执行的结果是一个长度为1的字符串,
-			FTL并没有独立的字符类型。和序列中的子变量一样,这个索引也必须是数字,
-			范围是从0到字符串的长度,否则模板的执行将会发生错误并终止。</para>
-
-            <para>由于序列的子变量语法和字符的getter语法冲突,
-			那么只能在变量不是序列时使用字符的getter语法(因为FTL支持多类型值,所以它是可能的),
-			这种情况下使用序列方式就比较多。(为了变通,可以使用 <link 
-			linkend="ref_builtin_string_for_string"> 
-			内建函数 <literal>string</literal> </link>,比如
-            <literal>user?string[0]</literal>。不必担心你不理解这是什么意思,
-			内建函数将会在后续章节中讨论。)</para>
-
-            <para>示例(假设 user 是 <quote>Big Joe</quote>):</para>
-
-            <programlisting role="template">${user[0]}
-${user[4]}</programlisting>
-
-            <para>将会输出(请注意第一个字符的索引是0):</para>
-
-            <programlisting role="output">B
-J</programlisting>
-          </section>
-
-          <section xml:id="dgui_template_exp_stringop_slice">
-            <title>字符串切分 (子串)</title>
-
-            <indexterm>
-              <primary>string slicing</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>substring</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>string</primary>
-
-              <secondary>slice</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>string</primary>
-
-              <secondary>substring</secondary>
-            </indexterm>
-
-            <para>可以按照 <link 
-			linkend="dgui_template_exp_seqenceop_slice">切分序列</link> 
-			(请参看)的相同方式来切分字符串,这就是使用字符来代替序列。不同的是:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>降序域不允许进行字符串切分。
-				(因为不像序列那样,很少情况下会想反转字符串。
-				如果真要这样做了,那就是疏忽。)</para>
-              </listitem>
-
-              <listitem>
-                <para>如果变量的值既是字符串又是序列(多类型值),
-				那么切分将会对序列进行,而不是字符串。当处理XML时,
-				这样的值就是普通的了。此时,可以使用
-                <literal><replaceable>someXMLnode</replaceable>?string[<replaceable>range</replaceable>]</literal>。</para>
-              </listitem>
-
-              <listitem>
-                <para>一个遗留的bug:值域 <emphasis>包含</emphasis> 结尾时,
-				结尾小于开始索引并且是是非负的(就像在 <literal>"abc"[1..0]</literal> 中),
-				会返回空字符串而不是错误。(在降序域中这应该是个错误。) 
-				现在这个bug已经向后兼容,但是不应该使用它,否在就会埋下一个错误。</para>
-              </listitem>
-            </itemizedlist>
-
-            <para>示例:</para>
-
-            <programlisting role="template">&lt;#assign s = "ABCDEF"&gt;
-${s[2..3]}
-${s[2..&lt;4]}
-${s[2..*3]}
-${s[2..*100]}
-${s[2..]}</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">CD
-CD
-CDE
-CDEF
-CDEF</programlisting>
-
-            <note>
-              <para>下面包括了一些使用内建函数来方便字符串切分的典型用例: <link
-              linkend="ref_builtin_remove_beginning"><literal>remove_beginning</literal></link>,
-              <link
-              linkend="ref_builtin_remove_ending"><literal>remove_ending</literal></link>,
-              <link
-              linkend="ref_builtin_keep_before"><literal>keep_before</literal></link>,
-              <link
-              linkend="ref_builtin_keep_after"><literal>keep_after</literal></link>,
-              <link
-              linkend="ref_builtin_keep_before_last"><literal>keep_before_last</literal></link>,
-              <link
-              linkend="ref_builtin_keep_after_last"><literal>keep_after_last</literal></link></para>
-            </note>
-          </section>
-        </section>
-
-        <section xml:id="dgui_template_exp_sequenceop">
-          <title>序列操作</title>
-
-          <indexterm>
-            <primary>sequence</primary>
-
-            <secondary>operations</secondary>
-          </indexterm>
-
-          <section xml:id="dgui_template_exp_sequenceop_cat">
-            <title>连接</title>
-
-            <indexterm>
-              <primary>concatenate sequences</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>joining sequences</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>sequence</primary>
-
-              <secondary>concatenate</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>adding sequences</primary>
-            </indexterm>
-
-            <para>序列的连接可以按照字符串那样使用 <literal>+</literal> 
-			号来进行,例如:</para>
-
-            <programlisting role="template">&lt;#list ["Joe", "Fred"] + ["Julia", "Kate"] as user&gt;
-- ${user}
-&lt;/#list&gt;</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">- Joe
-- Fred
-- Julia
-- Kate
- </programlisting>
-
-            <para>请注意,不要在很多重复连接时使用序列连接操作,
-			比如在循环中往序列上追加项目,而这样的使用是可以的:
-			<literal>&lt;#list users + admins as person&gt;</literal>。
-			尽管序列连接的速度很快,而且速度是和被连接序列的大小相独立的,
-			但是最终的结果序列的读取却比原先的两个序列慢那么一点。
-			通过这种方式进行的许多重复连接最终产生的序列读取的速度会慢。</para>
-          </section>
-
-          <section xml:id="dgui_template_exp_seqenceop_slice">
-            <title>序列切分</title>
-
-            <indexterm>
-              <primary>sequence slice</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>sequence</primary>
-
-              <secondary>slice</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>subsequence</primary>
-            </indexterm>
-
-            <para>使用
-            <literal><replaceable>seq</replaceable>[<replaceable>range</replaceable>]</literal>,
-            这里 <literal><replaceable>range</replaceable></literal> 是一个值域
-			<link linkend="dgui_template_exp_direct_ranges">此处有说明</link>,
-			就可以得到序列的一个切分。结果序列会包含原序列
-			(<literal><replaceable>seq</replaceable></literal>)中的项,
-			而且索引在值域中。例如:</para>
-
-            <programlisting role="template">&lt;#assert seq = ["A", "B", "C", "D", "E"]&gt;
-&lt;#list seq[1..3] as i&gt;${i}&lt;/#list&gt;</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">BCD </programlisting>
-
-            <para>此外,切分后序列中的项会和值域的顺序相同。
-			那么上面的示例中,如果值域是 <literal>3..1</literal> 将会输出
-            <literal>DCB</literal>。</para>
-
-            <para>值域中的数字必须是序列可使用的合法索引,
-			否则模板的处理将会终止并报错。像上面的示例那样,
-            <literal>seq[-1..0]</literal> 就会出错,
-			而 <literal>seq[-1]</literal> 就是合法的。
-            <literal>seq[1..5]</literal> 也不对,
-			因为 <literal>seq[5]</literal> 是非法的。
-			(请注意,尽管100已经越界,但是 
-			<literal>seq[100..&lt;100]</literal> 或 
-			<literal>seq[100..*0]</literal> 是合法的,因为那些值域都是空。)</para>
-
-            <para>限制长度的值域
-            (<literal><replaceable>start</replaceable>..*<replaceable>length</replaceable></literal>)
-            和无右边界值域 (<literal><replaceable>start</replaceable>..</literal>) 
-			适用于切分后序列的长度。它们会切分可用项中尽可能多的部分:</para>
-
-            <programlisting role="template">&lt;#assign seq = ["A", "B", "C"]&gt;
-
-Slicing with length limited ranges:
-- &lt;#list seq[0..*2] as i&gt;${i}&lt;/#list&gt;
-- &lt;#list seq[1..*2] as i&gt;${i}&lt;/#list&gt;
-- &lt;#list seq[2..*2] as i&gt;${i}&lt;/#list&gt; &lt;#-- Not an error --&gt;
-- &lt;#list seq[3..*2] as i&gt;${i}&lt;/#list&gt; &lt;#-- Not an error --&gt;
-
-Slicing with right-unlimited ranges:
-- &lt;#list seq[0..] as i&gt;${i}&lt;/#list&gt;
-- &lt;#list seq[1..] as i&gt;${i}&lt;/#list&gt;
-- &lt;#list seq[2..] as i&gt;${i}&lt;/#list&gt;
-- &lt;#list seq[3..] as i&gt;${i}&lt;/#list&gt;</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">Slicing with length limited ranges:
-- AB
-- BC
-- C
--
-
-Slicing with right-unlimited ranges:
-- ABC
-- BC
-- C
--</programlisting>
-
-            <para>请注意,上面的有限长度切分和无右边界切分都允许开始索引超过最后项
-            <emphasis>一个</emphasis> (但不能再多了)。</para>
-
-            <note>
-              <para>要对序列进行给定大小的切分,就应该使用内建函数 <link
-              linkend="ref_builtin_chunk"><literal>chunk</literal></link>。</para>
-            </note>
-          </section>
-        </section>
-
-        <section xml:id="dgui_template_exp_hashop">
-          <title>哈希表操作</title>
-
-          <indexterm>
-            <primary>hash</primary>
-
-            <secondary>operations</secondary>
-          </indexterm>
-
-          <section xml:id="dgui_template_exp_hashop_cat">
-            <title>连接</title>
-
-            <indexterm>
-              <primary>concatenate hashes</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>joining hashes</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>hash</primary>
-
-              <secondary>concatenate</secondary>
-            </indexterm>
-
-            <indexterm>
-              <primary>adding hashes</primary>
-            </indexterm>
-
-            <para>像连接字符串那样,也可以使用 <literal>+</literal> 
-			号的方式来连接哈希表。如果两个哈希表含有键相同的项,那么在 
-			<literal>+</literal> 号右侧的哈希表中的项优先。例如:</para>
-
-            <programlisting role="template">&lt;#assign ages = {"Joe":23, "Fred":25} + {"Joe":30, "Julia":18}&gt;
-- Joe is ${ages.Joe}
-- Fred is ${ages.Fred}
-- Julia is ${ages.Julia}
-</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">- Joe is 30
-- Fred is 25
-- Julia is 18</programlisting>
-
-            <para>请注意,很多项连接时不要使用哈希表连接,
-			比如在循环时往哈希表中添加新项。这和<link 
-			linkend="dgui_template_exp_sequenceop_cat">序列连接</link> 
-			的情况是一致的。</para>
-          </section>
-        </section>
-
-        <section xml:id="dgui_template_exp_arit">
-          <title>算数运算</title>
-
-          <indexterm>
-            <primary>arithmetic</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>math</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>addition</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>subtraction</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>division</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>modulus</primary>
-          </indexterm>
-
-          <para>算数运算包含基本的四则运算和求模运算,运算符有:</para>
-
-          <itemizedlist spacing="compact">
-            <listitem>
-              <para>加法: <literal>+</literal></para>
-            </listitem>
-
-            <listitem>
-              <para>减法: <literal>-</literal></para>
-            </listitem>
-
-            <listitem>
-              <para>乘法: <literal>*</literal></para>
-            </listitem>
-
-            <listitem>
-              <para>除法: <literal>/</literal></para>
-            </listitem>
-
-            <listitem>
-              <para>求模 (求余): <literal>%</literal></para>
-            </listitem>
-          </itemizedlist>
-
-          <remark>运算精度的问题?</remark>
-
-          <para>示例:</para>
-
-          <programlisting role="template">${100 - x * x}
-${x / 2}
-${12 % 10}</programlisting>
-
-          <para>假设 <literal>x</literal> 是 5,将会输出:</para>
-
-          <programlisting role="output">75
-2.5
-2</programlisting>
-
-          <para>要保证两个操作数都是结果为数字的表达式。
-		  下面的这个例子在运行时,FreeMarker就会发生错误,
-		  因为是字符串 <literal>"5"</literal> 而不是数字5:</para>
-
-          <programlisting role="template">${3 * "5"} &lt;#-- WRONG! --&gt;</programlisting>
-
-          <para>但这种情况也有一个例外,就是 <literal>+</literal> 号,它是用来 <link
-          linkend="dgui_template_exp_stringop_interpolation">连接字符串</link>的。
-		  如果 <literal>+</literal> 号的一端是字符串,<literal>+</literal> 
-		  号的另外一端是数字,那么数字就会自动转换为字符串类型(使用当前页面语言的适当格式),
-		  之后使用 <literal>+</literal> 号作为字符串连接操作符。示例如下:</para>
-
-          <programlisting role="template">${3 + "5"}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">35</programlisting>
-
-          <para>通常来说,FreeMarker不会自动将字符串转换为数字,反之会自动进行。</para>
-
-          <para><indexterm>
-              <primary>integer division</primary>
-            </indexterm><indexterm>
-              <primary>integer part</primary>
-            </indexterm>有时我们只想获取除法计算(或其它运算)的整数部分,
-			这可以使用内建函数 <literal>int</literal> 来解决。(关于内建函数
-			<link linkend="dgui_template_exp_builtin">后续章节</link>会来解释):</para>
-
-          <programlisting role="template">${(x/2)?int}
-${1.1?int}
-${1.999?int}
-${-1.1?int}
-${-1.999?int}</programlisting>
-
-          <para>假设 <literal>x</literal> 是 5,将会输出:</para>
-
-          <programlisting role="output">2
-1
-1
--1
--1</programlisting>
-        </section>
-
-        <section xml:id="dgui_template_exp_comparison">
-          <title>比较运算</title>
-
-          <indexterm>
-            <primary>comparison operators</primary>
-          </indexterm>
-
-          <para>有时我们需要知道两个值是否相等,或者哪个值更大一点。</para>
-
-          <para>为了演示具体的例子,我们在这里使用 <literal>if</literal> 指令。
-		  <literal>if</literal>  指令的用法是: <literal>&lt;#if 
-		  <replaceable>expression</replaceable>&gt;...&lt;/#if&gt;</literal>,
-		  其中的表达式的值必须是布尔类型,否则将会出错,模板执行中断。
-		  如果表达式的结果是 <literal>true</literal> ,
-		  那么在开始和结束标记内的内容将会被执行,否则就会被跳过。</para>
-
-          <para>测试两个值相等使用 <literal>=</literal>
-          (或者采用Java和C语言中的 <literal>==</literal> ;二者是完全等同的。) 
-		  测试两个值不等使用 <literal>!=</literal>。比如,
-		  假设 <literal>user</literal> 是 ''Big Joe'':</para>
-
-          <programlisting role="template">&lt;#if <emphasis>user == "Big Joe"</emphasis>&gt;
-  It is Big Joe
-&lt;/#if&gt;
-&lt;#if <emphasis>user != "Big Joe"</emphasis>&gt;
-  It is not Big Joe
-&lt;/#if&gt;</programlisting>
-
-          <para> <literal>&lt;#if ...&gt;</literal> 中的表达式 
-		  <literal>user = "Big Joe"</literal> 就是布尔值
-          <literal>true</literal>,面的代码将会输出 ''It is Big Joe''。</para>
-
-          <para> <literal>=</literal> 或 <literal>!=</literal> 
-		  两边的表达式的结果都必须是标量,而且两个标量都必须是相同类型
-		  (也就是说字符串只能和字符串来比较,数字只能和数字来比较等)否则将会出错,
-		  模板执行中断。例如  <literal>&lt;#if 1 = "1"&gt;</literal> 就会导致错误。
-		  请注意FreeMarker进行的是精确的比较,所以字符串在比较时要注意大小写和空格:
-		  <literal>"x"</literal> 和 <literal>"x "</literal> 
-		  和 <literal>"X"</literal> 是不同的值。</para>
-
-          <para>对数字和日期类型的比较,也可以使用 <literal>&lt;</literal>,
-		  <literal>&lt;=</literal>,<literal>&gt;=</literal> 和 
-		  <literal>&gt;</literal>。不能把它们当作字符串来比较。比如:</para>
-
-          <programlisting role="template">&lt;#if x <emphasis>&lt;=</emphasis> 12&gt;
-  x is less or equivalent with 12
-&lt;/#if&gt;</programlisting>
-
-          <para>使用 <literal>&gt;=</literal> 和 <literal>&gt;</literal> 
-		  的时候有一点小问题。FreeMarker解释 <literal>&gt;</literal> 
-		  的时候可以把它当作FTL标签的结束符。为了避免这种问题,可以使用
-		  <literal>lt</literal> 代替 <literal>&lt;</literal>,
-		  <literal>lte</literal> 代替 <literal>&lt;=</literal>,
-		  <literal>gt</literal> 代替 <literal>&gt;</literal> 还有
-		  <literal>gte</literal> 代替 <literal>&gt;=</literal>,
-		  例如 <literal>&lt;#if x gt y&gt;</literal>。另外一个技巧是将表达式放到 <link
-          linkend="dgui_template_exp_parentheses">圆括号</link> 中,
-		  尽管这么写并不优雅,例如 <literal>&lt;#if (x &gt; y)&gt;</literal>。</para>
-
-          <note>
-            <para>FreeMarker 也支持一些其它的选择,但是这些已经废弃了:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>在可能出问题的关系标记处使用 <literal>&amp;gt;</literal> 和
-                <literal>&amp;lt;</literal> ,就像: <literal>&lt;#if x &amp;gt;
-                y&gt;</literal> 或 <literal>&lt;#if x &amp;gt;=
-                y&gt;</literal>。 请注意通常FTL不支持标签中的实体引用(如
-                <literal>&amp;<replaceable>...</replaceable>;</literal> 这些东西);
-				做算术比较时就会有异常。</para>
-              </listitem>
-
-              <listitem>
-                <para><literal>\lt</literal>, <literal>\lte</literal>,
-                <literal>\gt</literal> 和 <literal>\gte</literal> 使用他们时,
-				不带反斜杠的效果一样。</para>
-              </listitem>
-            </itemizedlist>
-          </note>
-        </section>
-
-        <section xml:id="dgui_template_exp_logicalop">
-          <title>逻辑操作</title>
-
-          <indexterm>
-            <primary>boolean</primary>
-
-            <secondary>operations</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>logical operations</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>or</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>and</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>not</primary>
-          </indexterm>
-
-          <para>常用的逻辑操作符:</para>
-
-          <itemizedlist spacing="compact">
-            <listitem>
-              <para>逻辑 或: <literal>||</literal></para>
-            </listitem>
-
-            <listitem>
-              <para>逻辑 与: <literal>&amp;&amp;</literal></para>
-            </listitem>
-
-            <listitem>
-              <para>逻辑 非: <literal>!</literal></para>
-            </listitem>
-          </itemizedlist>
-
-          <para>逻辑操作符仅仅在布尔值之间有效,若用在其他类型将会产生错误导致模板执行中止。</para>
-
-          <para>例如:</para>
-
-          <programlisting role="template">&lt;#if x &lt; 12 <emphasis>&amp;&amp;</emphasis> color == "green"&gt;
-  We have less than 12 things, and they are green.
-&lt;/#if&gt;
-&lt;#if <emphasis>!</emphasis>hot&gt; &lt;#-- here hot must be a boolean --&gt;
-  It's not hot.
-&lt;/#if&gt;</programlisting>
-        </section>
-
-        <section xml:id="dgui_template_exp_builtin">
-          <title>内建函数</title>
-
-          <indexterm>
-            <primary>built-in</primary>
-          </indexterm>
-
-          <para>内建函数就像FreeMarker在对象中添加的方法一样。
-		  要防止和实际方法和其它子变量的命名冲突,则不能使用点
-		  (<literal>.</literal>),这里使用问号
-		  (<literal>?</literal>)来和父对象分隔开。
-		  比如,想要保证 <literal>path</literal> 有起始的 
-		  <literal>/</literal> ,那么可以这么来写:
-		  <literal>path?ensure_starts_with('/')</literal>。 
-		  <literal>path</literal> 后的Java对象(通常就是 <literal>String</literal>)
-		  并没有这样的方法,这是FreeMarker添加的。为了简洁,如果方法没有参数,
-		  那么就可以忽略 <literal>()</literal>,比如想要获取 
-		  <literal>path</literal> 的长度,就可以写作:<literal>path?length</literal>,
-		  <emphasis>而不是</emphasis> <literal>path?length()</literal>。</para>
-
-          <para>内建函数关键性的另外一个原因是常见的(尽管它依赖于配置的设置),
-		  FreeMarker不会暴露对象的Java API。那么尽管Java的 <literal>String</literal> 
-		  类有 <literal>length()</literal> 方法,但在模板中却是不可见的,
-		  就 <emphasis>不得不</emphasis> 使用 <literal>path?length</literal> 来代替。
-		  这里的优点是模板不依赖下层Java对象的精确类型。(比如某些场景中,
-		  <literal>path</literal> 也可能是 <literal>java.nio.Path</literal> 类型,
-		  如果程序员配置了FreeMarker去暴露 <literal>Path</literal> 
-		  对象作为FTL字符串类型,那么模板就不会在意了,使用 
-		  <literal>?length</literal> 也是可以的,
-		  即便 <literal>java.nio.Path</literal> 没有类似的方法。)</para>
-
-          <para>可以找到一些 <link
-          linkend="topic.commonlyUsedBuiltIns">此处提及的常用内建函数</link>,还有
-		  <link linkend="ref_builtins">完整的内建函数参考</link>。
-		  现在,我们只需了解一些重要的内建函数就行了:</para>
-
-          <para>比如:</para>
-
-         <programlisting role="template">${testString?upper_case}
-${testString?html}
-${testString?upper_case?html}
-
-${testSequence?size}
-${testSequence?join(", ")}</programlisting>
-
-          <para>假设 <literal>testString</literal> 中存储了字符串
-          ''Tom &amp; Jerry'', 而testSequnce中存储了字符串
-          <quote>foo</quote>, <quote>bar</quote> 和 <quote>baz</quote>,
-		  将会输出:</para>
- 
-          <programlisting role="output">TOM &amp; JERRY
-Tom &amp;amp; Jerry
-TOM &amp;amp; JERRY
-
-3
-foo, bar, baz</programlisting>
-
-          <para>请注意:上面的 <literal>testString?upper_case?html</literal>。因为
-          <literal>test?upper_case</literal> 的结果是字符串,那么就可以在它的上面
-		  使用内建函数 <literal>html</literal>。</para>
-
-          <para>很自然可以看到,内建函数的左侧可以是任意的表达式,而不仅仅是变量名:</para>
-
-          <programlisting role="template">${testSeqence[1]?cap_first}
-${"horse"?cap_first}
-${(testString + " &amp; Duck")?html}</programlisting>
-
-          <programlisting role="output">Bar
-Horse
-Tom &amp;amp; Jerry &amp;amp; Duck</programlisting>
-        </section>
-
-        <section xml:id="dgui_template_exp_methodcall">
-          <title>方法调用</title>
-
-          <indexterm>
-            <primary>call a method</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>method</primary>
-
-            <secondary>call</secondary>
-          </indexterm>
-
-          <para>如果有一个方法,那么可以使用方法调用操作。
-		  方法调用操作是使用逗号来分割在括号内的表达式而形成参数列表,这些值就是参数。
-		  方法调用操作将这些值传递给方法,然后返回一个结果。
-		  这个结果就是整个方法调用表达式的值。</para>
-
-          <para>假设程序员定义了一个可供调用的方法 <literal>repeat</literal>。
-		  第一个参数是字符串类型,第二个参数是数字类型。方法的返回值是字符串类型,
-		  而方法要完成的操作是将第一个参数重复显示,显示的次数是第二个参数设定的值。</para>
-
-          <programlisting role="template">${repeat("Foo", 3)}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">FooFooFoo</programlisting>
-
-          <para>这里的 <literal>repeat</literal> 就是方法变量(根据如何 <link
-          linkend="dgui_template_exp_var_toplevel">访问顶层变量</link>),
-		  <literal>("What", 3)</literal> 就调用了该方法。</para>
-
-          <para>这里需要强调方法调用也是普通表达式,和其它都是一样的,所以:</para>
-
-          <programlisting role="template">${repeat(repeat("x", 2), 3) + repeat("Foo", 4)?upper_case}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">xxxxxxFOOFOOFOOFOO</programlisting>
-        </section>
-
-        <section xml:id="dgui_template_exp_missing">
-          <title>处理不存在的值</title>
-
-          <note>
-            <para>这些操作符是从 FreeMarker 2.3.7 版本开始引入的(用来代替内建函数
-            <literal>default</literal>, <literal>exists</literal> 和
-            <literal>if_exists</literal> )。</para>
-          </note>
-
-          <indexterm>
-            <primary>undefined variable</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>missing variable</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>null</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>handling null-s</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>error handling</primary>
-          </indexterm>
-
-          <para>正如我们前面解释的那样,当试图访问一个不存在的变量时,
-		  FreeMarker 将会报错而导致模板执行中断。
-		  通常我们可以使用两个特殊操作符来压制这个错误,控制这种错误情况。
-		  被控制的变量可以是顶层变量,哈希表或序列的子变量。
-		  此外这些操作符还能处理方法调用的返回值不存在的情况 
-		  <phrase role="forProgrammers">(这点对Java程序员来说:
-		  返回值是 <literal>null</literal> 或者返回值为 <literal>void</literal> 
-		  类型)</phrase>,通常来说,我们应该使用这些操作符来控制可能不存在的值,
-		  而不仅仅是不存在的变量。</para>
-
-          <para><phrase role="forProgrammers">对于知道Java中 
-		  <literal>null</literal> 的人来说,FreeMarker 2.3.<replaceable>x</replaceable> 
-		  版本把它们视为不存在的变量。单地说,模板语言中没有 <literal>null</literal> 
-		  这个概念。比如有一个bean,bean中有一个 <literal>maidenName</literal> 属性,
-		  对于模板而言(假设没有配置FreeMarker来使用一些极端的对象包装),
-		  该属性的值是 <literal>null</literal>,和不存在这个属性的情况是一致的。
-		  调用方法的返回值如果是  <literal>null</literal> 
-		  的话 FreeMarker 也会把它当作不存在的变量来处理
-		  (假定只使用了普通的对象包装)。可以在 <link linkend="faq_null">FAQ</link> 
-		  中了解更多内容。</phrase></para>
-
-          <note>
-            <para>如果想知道为什么 FreeMarker 对不存在的变量如此挑剔,
-			请阅读 <link linkend="faq_picky_about_missing_vars">FAQ</link> 部分。</para>
-          </note>
-
-          <section xml:id="dgui_template_exp_missing_default">
-            <title>默认值操作符</title>
-
-            <indexterm>
-              <primary>default value operator</primary>
-            </indexterm>
-
-            <para>使用形式:
-            <literal><replaceable>unsafe_expr</replaceable>!<replaceable>default_expr</replaceable></literal>
-            或 <literal><replaceable>unsafe_expr</replaceable>!</literal> or
-            <literal>(<replaceable>unsafe_expr</replaceable>)!<replaceable>default_expr</replaceable></literal>
-            或
-            <literal>(<replaceable>unsafe_expr</replaceable>)!</literal></para>
-
-            <para>这个操作符允许你为可能不存在的变量指定一个默认值。</para>
-
-            <para>例如,假设下面展示的代码中没有名为 <literal>mouse</literal> 的变量:</para>
-
-            <programlisting role="template">${mouse!"No mouse."}
-&lt;#assign mouse="Jerry"&gt;
-${mouse!"No mouse."}</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">No mouse.
-Jerry</programlisting>
-
-            <para>默认值可以是任何类型的表达式,也可以不必是字符串。
-			也可以这么写:<literal>hits!0</literal> 或 
-			<literal>colors!["red", "green", "blue"]</literal>。
-			默认值表达式的复杂程度没有严格限制,还可以这么来写:
-			<literal>cargo.weight!(item.weight * itemCount + 10)</literal>。</para>
-
-            <warning>
-              <para>如果在 <literal>!</literal>后面有复合表达式,
-			  如 <literal>1 + x</literal>,<emphasis>通常</emphasis> 
-			  使用括号,如 <literal>${x!(1 + y)}</literal> 或 
-			  <literal>${(x!1) + y)}</literal>,这样就根据你的意图来确定优先级。
-			  由于FreeMarker 2.3.x 版本的源码中的小失误所以必须这么来做。 
-			  <literal>!</literal> (作为默认值操作) 右侧的优先级非常低。 
-			  这就意味着 <literal>${x!1 + y}</literal> 会被 FreeMarker 
-			  误解为 <literal>${x!(1 + y)}</literal>,而真实的意义是 
-			  <literal>${(x!1) + y}</literal>。 这个源码错误在FreeMarker 2.4中会得到修正。
-			  在编程中注意这个错误,要么就使用FreeMarker 2.4!</para>
-            </warning>
-
-            <para>如果默认值被省略了,那么结果将会是空串,空序列或空哈希表。
-			(这是 FreeMarker 允许多类型值的体现)请注意,如果想让默认值为 
-			<literal>0</literal> 或 <literal>false</literal>,则不能省略它。例如:</para>
-
-            <programlisting role="template">(${mouse!})
-&lt;#assign mouse = "Jerry"&gt;
-(${mouse!})</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">()
-(Jerry)</programlisting>
-
-            <warning>
-              <para>因为语法的含糊 <literal>&lt;@something a=x! b=y /&gt;</literal> 
-			  将会解释为 <literal>&lt;@something a=x!(b=y) /&gt;</literal>,那就是说
-              <literal>b=y</literal> 将会被视为是比较运算,然后结果作为 
-			  <literal>x</literal>的默认值,而不是想要的参数  <literal>b</literal>。
-			  为了避免这种情况,如下编写代码即可: <literal>&lt;@something a=(x!) b=y
-              /&gt;</literal></para>
-            </warning>
-
-            <para>用于非顶层变量时,默认值操作符可以有两种使用方式:</para>
-
-            <programlisting role="template">product.color!"red"</programlisting>
-
-            <para>如果是这样的写法,那么在 <literal>product</literal> 中,
-			当 <literal>color</literal> 不存在时(返回 <literal>"red"</literal> ),
-			将会被处理,但是如果连 <literal>product</literal> 都不存在时将不会处理。
-			也就是说这样写时变量 <literal>product</literal> 必须存在,否则模板就会报错。</para>
-
-            <programlisting role="template">(product.color)!"red"</programlisting>
-
-            <para>这时,如果当 <literal>product.color</literal> 不存在时也会被处理,
-			那就是说,如果 <literal>product</literal> 不存在或者 
-			<literal>product</literal> 存在而 <literal>color</literal> 
-			不存在,都能显示默认值 <literal>"red"</literal> 而不会报错。
-			本例和上例写法的重要区别在于用括号时,
-			就允许其中表达式的任意部分可以未定义。而没有括号时,
-			仅允许表达式的最后部分可以不被定义。</para>
-
-            <para>当然,默认值操作也可以作用于序列子变量,比如:</para>
-
-            <programlisting role="template">&lt;#assign seq = ['a', 'b']&gt;
-${seq[0]!'-'}
-${seq[1]!'-'}
-${seq[2]!'-'}
-${seq[3]!'-'}</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">a
-b
--
--</programlisting>
-
-            <para>如果序列索引是负数(比如 <literal>seq[-1]!'-'</literal>)
-			也会发生错误,不能使用该运算符或者其它运算符去压制它。</para>
-          </section>
-
-          <section xml:id="dgui_template_exp_missing_test">
-            <title>不存在值检测操作符</title>
-
-            <indexterm>
-              <primary>existence test operator</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>missing value test operator</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>testing for null</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>testing for missing</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>testing for undefined</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>is null</primary>
-            </indexterm>
-
-            <para>使用形式:
-            <literal><replaceable>unsafe_expr</replaceable>??</literal> 或
-            <literal>(<replaceable>unsafe_expr</replaceable>)??</literal></para>
-
-            <para>这个操作符告诉我们一个值是否存在。基于这种情况,
-			结果是 <literal>true</literal> 或 <literal>false</literal>。</para>
-
-            <para>示例如下,假设并没有名为 <literal>mouse</literal> 的变量:</para>
-
-            <programlisting role="template">&lt;#if mouse??&gt;
-  Mouse found
-&lt;#else&gt;
-  No mouse found
-&lt;/#if&gt;
-Creating mouse...
-&lt;#assign mouse = "Jerry"&gt;
-&lt;#if mouse??&gt;
-  Mouse found
-&lt;#else&gt;
-  No mouse found
-&lt;/#if&gt;</programlisting>
-
-            <para>将会输出:</para>
-
-            <programlisting role="output">  No mouse found
-Creating mouse...
-  Mouse found</programlisting>
-
-            <para>访问非顶层变量的使用规则和默认值操作符也是一样的,
-			也就是说,可以写 <literal>product.color??</literal> 
-			和 <literal>(product.color)??</literal>。</para>
-          </section>
-        </section>
-
-        <section xml:id="dgui_template_exp_assignment">
-          <title>赋值操作符</title>
-
-          <para>这些并不是表达式,只是复制指令语法的一部分,比如 <link
-          linkend="ref_directive_assign"><literal>assign</literal></link>,
-          <link linkend="ref_directive_local"><literal>local</literal></link>
-          和 <link
-          linkend="ref_directive_global"><literal>global</literal></link>。
-		  照这样,它们不能任意被使用。</para>
-
-          <para><literal>&lt;#assign x += y&gt;</literal> 是
-          <literal>&lt;#assign x = x + y&gt;</literal> 的简写,<literal>&lt;#assign x
-          *= y&gt;</literal> 是 <literal>&lt;#assign x = x *
-          y&gt;</literal>的简写等等。。。</para>
-
-          <para><literal>&lt;#assign x++&gt;</literal> 和
-          <literal>&lt;#assign x += 1&gt;</literal> (或 <literal>&lt;#assign x
-          = x + 1&gt;</literal>)不同,它只做算术加法运算
-          (如果变量不是数字的话就会失败),而其它的是进行字符串,序列连接和哈希表连接的重载。
-		  <literal>&lt;#assign x--&gt;</literal> 是
-          <literal>&lt;#assign x -= 1&gt;</literal> 的简写。</para>
-        </section>
-
-        <section xml:id="dgui_template_exp_parentheses">
-          <title>括号</title>
-
-          <indexterm>
-            <primary>parentheses</primary>
-          </indexterm>
-
-          <para>括号可以用来给任意表达式分组。示例如下:</para>
-
-          <programlisting role="template">                               &lt;#-- Output will be: --&gt;
-${3 * 2 + 2}                   &lt;#-- 8 --&gt;
-${3 * (2 + 2)}                 &lt;#-- 12 --&gt;
-${3 * ((2 + 2) * (1 / 2))}     &lt;#-- 6 --&gt;
-${"green " + "mouse"?upper_case}    &lt;#-- green MOUSE --&gt;
-${("green " + "mouse")?upper_case}  &lt;#-- GREEN MOUSE --&gt;
-&lt;#if !(color == "red" || color == "green")&gt;
-  The color is nor red nor green
-&lt;/#if&gt;</programlisting>
-
-          <para>请注意,<link linkend="dgui_template_exp_methodcall">方法调用表达式</link> 
-		  使用的括号和给表达式分组的括号含义是完全不同的。</para>
-        </section>
-
-        <section xml:id="dgui_template_exp_whitespace">
-          <title>表达式中的空格</title>
-
-          <para>FTL 忽略表达式中的多余的 <link 
-		  linkend="gloss.whiteSpace">空格</link>。下面的表示是相同的:</para>
-
-          <programlisting role="template">${x + ":" + book.title?upper_case}</programlisting>
-
-          <para>和</para>
-
-          <programlisting role="template">${x+":"+book.title?upper_case}</programlisting>
-
-          <para>和</para>
-
-          <programlisting role="template">${
-   x
- + ":"   +  book   .   title
-   ?   upper_case
-      }</programlisting>
-        </section>
-
-        <section xml:id="dgui_template_exp_precedence">
-          <title>操作符的优先级</title>
-
-          <indexterm>
-            <primary>precedence</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>operator precedence</primary>
-          </indexterm>
-
-          <para>下面的表格显示了已定义操作符的优先级。
-		  表格中的运算符按照优先程度降序排列:上面的操作符优先级高于它下面的。
-		  高优先级的运算符执行要先于优先级比它低的。表格同一行上的两个操作符优先级相同。
-		  当有相同优先级的二元运算符(运算符有两个''参数'',比如
-		  <literal>+</literal>和<literal>-</literal>)挨着出现时,它们按照从左到右的原则运算。</para>
-
-          <informaltable border="1">
-            <thead>
-              <tr>
-                <th>运算符组</th>
-
-                <th>运算符</th>
-              </tr>
-            </thead>
-
-            <tbody>
-              <tr>
-                <td>最高优先级运算符</td>
-
-                <td><literal>[<replaceable>subvarName</replaceable>]
-                [<replaceable>subStringRange</replaceable>] . ?
-                (<replaceable>methodParams</replaceable>)
-                <replaceable>expr</replaceable>!
-                <replaceable>expr</replaceable>??</literal></td>
-              </tr>
-
-              <tr>
-                <td>一元前缀运算符</td>
-
-                <td><literal>+<replaceable>expr</replaceable>
-                -<replaceable>expr</replaceable> !expr</literal></td>
-              </tr>
-
-              <tr>
-                <td>乘除法,求模运算符</td>
-
-                <td><literal>* / %</literal></td>
-              </tr>
-
-              <tr>
-                <td>加减法运算符</td>
-
-                <td><literal>+ -</literal></td>
-              </tr>
-
-              <tr>
-                <td>数字值域</td>
-
-                <td><literal>..</literal> <literal>..&lt;</literal>
-                <literal>..!</literal> <literal>..*</literal></td>
-              </tr>
-
-              <tr>
-                <td>关系运算符</td>
-
-                <td><literal>&lt; &gt; &lt;= &gt;=</literal> (and equivalents:
-                <literal>gt</literal>, <literal>lt</literal>, etc.)</td>
-              </tr>
-
-              <tr>
-                <td>相等,不等运算符</td>
-
-                <td><literal>== !=</literal> (and equivalents:
-                <literal>=</literal>)</td>
-              </tr>
-
-              <tr>
-                <td>逻辑 <quote>与</quote> 运算符</td>
-
-                <td><literal>&amp;&amp;</literal></td>
-              </tr>
-
-              <tr>
-                <td>逻辑 <quote>或</quote> 运算符</td>
-
-                <td><literal>||</literal></td>
-              </tr>
-            </tbody>
-          </informaltable>
-
-          <para>如果你熟悉C语言,Java语言或JavaScript语言,
-		  请注意 FreeMarker 中的优先级规则和它们是相同的,
-		  除了那些只有FTL本身含有的操作符。</para>
-
-          <para>因为编程的失误,默认值操作符
-          (<literal><replaceable>exp</replaceable>!<replaceable>exp</replaceable></literal>)
-          不在上面的表格中,按照向后兼容的原则,在 FreeMarker 2.4 版本中将会修正它。
-		  而且它将是最高优先级的运算符,但是在 FreeMarker 2.3.x 
-		  版本中它右边的优先级由于失误就非常低。
-		  所以在默认值操作符的右边中使用复杂表达式时可以使用括号,
-		  可以是 <literal>x!(y + 1)</literal> 或者是 <literal>(x!y) + 1</literal>。
-		  而不能是 <literal>x!y + 1</literal>。</para>
-        </section>
-      </section>
-
-      <section xml:id="dgui_template_valueinsertion">
-        <title>插值</title>
-
-        <indexterm>
-          <primary>interpolation</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>${...}</primary>
-        </indexterm>
-
-        <section>
-          <title>概览</title>
-
-          <para>插值的使用格式是:
-		  <literal>${<replaceable>expression</replaceable>}</literal>,这里的
-          <literal><replaceable>expression</replaceable></literal> 
-		  可以是所有种类的表达式(比如 <literal>${100 + x}</literal>)。</para>
-
-          <para>插值是用来给 <literal><replaceable>表达式</replaceable></literal> 
-		  插入具体值然后转换为文本(字符串)。插值仅仅可以在两种位置使用:在 <link 
-		  linkend="dgui_template_overallstructure"><phrase 
-          role="markedText">文本</phrase> 区</link> (比如
-          <literal>&lt;h1&gt;Hello ${name}!&lt;/h1&gt;</literal>) 和 <link
-          linkend="dgui_template_exp_stringop_interpolation">字符串表达式</link> 
-		  (比如 <literal>&lt;#include "/footer/${company}.html"&gt;</literal>)中。</para>
-
-          <para>表达式的结果必须是字符串,数字或者日期/时间/日期-时间值,
-		  因为(默认是这样)仅仅这些值可以被插值自动转换为字符串。其它类型的值
-		  (比如布尔值,序列)必须 <quote>手动地</quote> 转换成字符串(后续会有一些建议),
-		  否则就会发生错误,中止模板执行。</para>
-
-          <warning>
-            <para>一个常犯的错误是在不能使用插值的地方使用了它。
-			插值  <emphasis>仅仅</emphasis> 在 <link
-          linkend="dgui_template_overallstructure"><phrase
-          role="markedText">文本</phrase> 区</link> (比如
-          <literal>&lt;h1&gt;Hello ${name}!&lt;/h1&gt;</literal>) 和 <link
-          linkend="dgui_template_exp_direct_string">字符串</link>
-          (比如 <literal>&lt;#include "/footer/${company}.html"&gt;</literal>)中起作用。
-		  典型的 <emphasis>错误</emphasis> 使用是 <literal>&lt;#if
-          ${big}&gt;...&lt;/#if&gt;</literal>,这是语法上的错误。
-		  只要简单写为 <literal>&lt;#if big&gt;...&lt;/#if&gt;</literal>即可。
-		  而且 <literal>&lt;#if "${big}"&gt;...&lt;/#if&gt;</literal> 也是 
-		  <emphasis>错误</emphasis>的,因为这样参数就是字符串类型了,
-		  但是 <literal>if</literal> 指令的参数要求是布尔值,所以就会发生运行时错误。</para>
-          </warning>
-        </section>
-
-        <section>
-          <title>字符串插入指南:不要忘了转义!</title>
-
-          <para>如果插值在 <link linkend="dgui_template_overallstructure"><phrase
-          role="markedText">文本</phrase> 区</link> (也就是说,不在 <link
-          linkend="dgui_template_exp_stringop_interpolation">字符串表达式</link> 中),如果 <link
-          linkend="ref.directive.escape"><literal>escape</literal>
-          指令</link> 起作用了,那么将被插入的字符串会被自动转义。如果要生成HTML,
-		  那么强烈建议你利用它来阻止跨站脚本攻击和非格式良好的HTML页面。这里有一个示例:</para>
-
-          <programlisting role="template"><emphasis>&lt;#escape x as x?html&gt;</emphasis>
-  ...
-  &lt;p&gt;Title: <emphasis>${</emphasis>book.title<emphasis>}</emphasis>&lt;/p&gt;
-  &lt;p&gt;Description: <emphasis>&lt;#noescape&gt;${</emphasis>book.description<emphasis>}&lt;/#noescape&gt;</emphasis>&lt;/p&gt;
-  &lt;h2&gt;Comments:&lt;/h2&gt;
-  &lt;#list comments as comment&gt;
-    &lt;div class="comment"&gt;
-      <emphasis>${</emphasis>comment<emphasis>}</emphasis>
-    &lt;/div&gt;
-  &lt;/#list&gt;
-  ...
-<emphasis>&lt;/#escape&gt;</emphasis></programlisting>
-
-          <para>这个示例展示了当生成HTML时,最好将完整的模板放入到 
-		  <literal>escape</literal> 指令中。那么,如果 
-		  <literal>book.title</literal> 包含 <literal>&amp;</literal>,
-		  在输出中它就会被替换成 <literal>&amp;amp;</literal>, 
-		  而页面还会保持为格式良好的HTML。如果用户注释包含如 
-		  <literal>&lt;iframe&gt;</literal>(或其它元素)的标记,那么就会被转义成
-          <literal>&amp;lt;iframe&amp;gt;</literal> 的样子,使他们没有任何有害点。
-          但有时在数据模型中真的需要HTML,我们假设上面的 
-		  <literal>book.description</literal> 在数据库中的存储是HTML格式的,
-		  那么此时不得不使用 <literal>noescape</literal> 来抵消
-          <literal>escape</literal> 的转义,不包含 <literal>escape</literal>,
-		  模板就会像这样了:</para>
-
-          <programlisting role="template">  ...
-  &lt;p&gt;Title: ${book.title?html}&lt;/p&gt;
-  &lt;p&gt;Description: ${book.description}&lt;/p&gt;
-  &lt;h2&gt;Comments:&lt;/h2&gt;
-  &lt;#list comments as comment&gt;
-    &lt;div class="comment"&gt;
-      ${comment?html}
-    &lt;/div&gt;
-  &lt;/#list&gt;
-  ...</programlisting>
-
-          <para>这和之前示例的效果是一样的, 但是这里可能会忘记 
-		  <literal>?html</literal> 等内建函数,那么这就会有安全上的问题了。
-		  在之前的示例中,你可能忘记 <literal>noescape</literal> 等内建函数,
-		  也会造成不良的输出,但是起码是没有安全隐患的。</para>
-        </section>
-
-        <section>
-          <title>数字插入指南</title>
-
-          <para>如果表达式是数字类型,那么根据数字的默认格式,
-		  数值将会转换成字符串。这也许会包含最大的小数,
-		  数字分组和相似处理的问题。通常程序员应该设置默认的数字格式;
-		  而模板设计者不需要处理它(但是可以使用 <literal>number_format</literal> 
-		  来设置;详情请参考 <link linkend="ref_directive_setting"> 
-		  <literal>setting</literal> 指令部分的文档</link>)。
-		  可以使用<link linkend="ref_builtin_string_for_number"> 
-		  内建函数 <literal>string</literal> </link>
-		  为一个插值来重写默认数值格式。</para>
-
-          <para>小数的分隔符通常(其他类似的符号也是这样,如分组符号)
-		  是根据所在地的标准(语言,国家)来确定的,这也需要程序员来设置。例如这个模板:</para>
-
-          <programlisting role="template">${1.5}</programlisting>
-
-          <para>如果当前本地化设置为英语时,将会输出:</para>
-
-          <programlisting role="output">1.5</programlisting>
-
-          <para>而当前地区为德国时,将会输出:</para>
-
-          <programlisting role="output">1,5</programlisting>
-
-          <para>这是因为德国人使用逗号作为小数点。</para>
-
-          <warning>
-            <para>可以看出,插值的打印都是给用户看的(至少是这样的),
-			而不是给''计算机''的。有时候这样并不好,比如要打印数据库记录的主键,
-			用来作为URL中的一部分或HTML表单的隐藏域来作为提交内容,
-			或者要打印CSS/JavaScript中的数字,因为这些值都是给计算机程序去识别的而不是给用户看的。
-			很多程序对数字格式的要求非常严格,它们只能理解一部分简单的美式数字格式。那样的话,
-			可以使用内建函数<link linkend="ref_builtin_c"><literal>c</literal></link> 
-			(代表''计算机'')来解决这个问题,比如:</para>
-
-            <programlisting role="template">&lt;a href="/shop/productdetails?id=${product.id?c}"&gt;Details...&lt;/a&gt;</programlisting>
-          </warning>
-        </section>
-
-        <section xml:id="dgui_template_valueinserion_universal_date">
-          <title>日期/时间插入指南</title>
-
-          <para>如果表达式的值是时间日期类型,那么日期中的数字将会按照默认格式来转换成文本。
-		  通常程序员应该设置默认格式,而页面设计者无需处理这一点。(如果需要的话,
-		  <link linkend="topic.dateTimeFormatSettings">可以参考
-          <literal>date_format</literal>, <literal>time_format</literal> 和
-          <literal>datetime_format</literal> 的 </link> 
-		  <link linkend="ref.directive.setting"><literal>setting</literal>
-          指令</link>设置)。当然,也可以使用
-		  <link linkend="ref_builtin_string_for_date">内建函数<literal>string</literal></link>
-		  来覆盖单独插值的默认格式。</para>
-
-          <warning>
-            <para>为了将日期显示成文本,FreeMarker 必须知道日期中的哪一部分在使用,也就是说,
-			如果仅仅日期部分(年,月,日)使用或仅仅时间部分(时,分,秒,毫秒)使用或两部分都用。
-			不幸的是,由于Java平台技术的限制,自动探测一些变量是不现实的。
-			这时可以找程序员对数据模型中可能出问题的变量进行处理。
-			如果找出时间日期变量的哪部分在使用是不太可能的话,就必须帮助 FreeMarker 使用内建函数
-			<link linkend="ref_builtin_date_datetype"><literal>date</literal>,
-            <literal>time</literal> 和 <literal>datetime</literal></link> 来识别
-			(比如 <literal>${lastUpdated?datetime}</literal> ),否则就会出现错误停止执行。</para>
-          </warning>
-        </section>
-
-        <section>
-          <title>布尔值插入指南</title>
-
-          <para>若要使用插值方式来打印布尔值会引起错误,中止模板的执行。
-		  例如: <literal>${a == 2}</literal> 就会引起错误,
-		  它不会打印''true''或其他内容。这是因为没有全局来表示布尔值的好方法
-		  (有时想输出yes/no,但有时是想要enabled/disabled,on/off等等)。</para>
-
-          <para>我们可以使用内建函数 <link 
-		  linkend="ref_builtin_string_for_boolean"><literal>?string</literal></link>
-		  来将布尔值转换为字符串形式。比如输出变量"married"的值(假设它是一个布尔值),
-		  那么可以这么来写: <literal>${married?string("yes", "no")}</literal>。</para>
-
-          <para>可以使用设置参数 <literal>boolean_format</literal> 
-		  来为 FreeMarker 配置默认的布尔值格式。那么,直接编写 
-		  <literal>${married}</literal> 这样的代码就不会有问题了。但在很多应用程序中,
-		  这样的做法是不推荐使用的,因为布尔值在不同的地方就应该呈现出不同的格式,
-		  同时将格式留作默认值也可以认为是疏忽,因为这可能导致错误产生。</para>
-
-          <para>当想生成JavaScript或其它计算机语言代码部分时,那么可以考虑使用 
-		  <literal>${someBoolean?c}</literal>(<quote>c</quote> 代表计算机)来输出布尔值true/false。
-		  (请记住 <literal>?c</literal> 也可以用来输出给计算机看的数字。)</para>
-        </section>
-
-        <section>
-          <title>精确的转换规则</title>
-
-          <para>对于有兴趣研究的人,表达式的值转换为字符串(仍受限于转义)
-		  精确的规则就是下面这些,以这个顺序进行:</para>
-
-          <orderedlist>
-            <listitem>
-              <para>如果这个值是数字,那么它会按照指定的 <literal>number_format</literal> 
-			  设置规则来转换为字符串。所以这些转换通常是对用户进行的,而不是对计算机。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果这个值是日期,时间或时间日期类型的一种,那么它们会按照指定的
-              <literal>date_format</literal>, <literal>time_format</literal>
-              或者 <literal>datetime_format</literal> 设置规则来转换为字符串。
-			  如果它不能被探测出来是哪种日期类型(日期或时间或日期时间)时,就会发生错误了。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果值本来就是字符串类型的,不需要转换。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 FreeMarker 引擎在传统兼容模式下:</para>
-
-              <orderedlist>
-                <listitem>
-                  <para>如果值是布尔类型,true值就转换成"true",false值将会转换为空字符串。</para>
-                </listitem>
-
-                <listitem>
-                  <para>如果表达式未被定义(<literal>null</literal> 或者变量未定义),
-				  那么就转换为空字符串。</para>
-                </listitem>
-
-                <listitem>
-                  <para>否则就会发生错误中止模板执行。</para>
-                </listitem>
-              </orderedlist>
-            </listitem>
-
-            <listitem>
-              <para>否则就会发生错误中止模板执行。</para>
-            </listitem>
-          </orderedlist>
-        </section>
-      </section>
-    </chapter>
-
-    <chapter xml:id="dgui_misc">
-      <title>其它</title>
-
-      <remark>Do we need a short chapter on i18n/charset issues in general,
-      with the introduction of FreeMarker facilities on this field at the
-      end?</remark>
-
-      <section xml:id="dgui_misc_userdefdir">
-        <title>自定义指令</title>
-
-        <indexterm>
-          <primary>macro</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>transform</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>custom directive</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>user-defined directive</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>directive</primary>
-
-          <secondary>user-defined</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>tag</primary>
-
-          <secondary>user-defined</secondary>
-        </indexterm>
-
-        <para>自定义指令可以使用 <literal>macro</literal> 指令来定义,
-		这是模板设计者所关心的内容。<phrase role="forProgrammers">
-		Java程序员若不想在模板中实现定义指令,而是在Java语言中实现指令的定义,
-		这时可以使用 <literal>freemarker.template.TemplateDirectiveModel</literal> 类来扩展
-		(请参考 <link linkend="pgui_datamodel_directive">后续章节</link>)。</phrase></para>
-
-        <section>
-          <title>基本内容</title>
-
-          <indexterm>
-            <primary>defining macro</primary>
-          </indexterm>
-
-          <para>宏是有一个变量名的模板片段。可以在模板中使用宏作为自定义指令,
-		  这样就能进行重复性的工作。例如,创建一个宏变量来输出大字号的''Hello Joe!'':</para>
-
-          <programlisting role="template"><emphasis>&lt;#macro greet&gt;</emphasis>
-  &lt;font size="+2"&gt;Hello Joe!&lt;/font&gt;
-<emphasis>&lt;/#macro&gt;</emphasis></programlisting>
-
-          <para><literal>macro</literal> 指令自身不输出任何内容,
-		  它只是用来创建宏变量,所以就会有一个名为 <literal>greet</literal> 
-		  的变量。在 <literal>&lt;#macro greet&gt;</literal> 和
-          <literal>&lt;/#macro&gt;</literal> 之间的内容
-		  (称为 <emphasis role="term">宏定义体</emphasis>)
-		  将会在使用该变量作为指令时执行。可以在FTL标记中通过 
-		  <literal>@</literal>代替<literal>#</literal>来使用自定义指令。
-		  使用变量名作为指令名。而且,自定义指令的 <link 
-		  linkend="gloss.endTag">结束标记</link> 也是需要的。那么,
-		  就可以这样来使用 <literal>greet</literal>:</para>
-
-          <programlisting role="template">&lt;@greet&gt;&lt;/@greet&gt;</programlisting>
-
-          <para>因为
-          <literal>&lt;<replaceable>anything</replaceable>&gt;&lt;/<replaceable>anything</replaceable>&gt;</literal> 和
-          <literal>&lt;<replaceable>anything</replaceable>/&gt;</literal> 是相同的,
-		  也可以使用单标记形式(如果你了解 <link linkend="gloss.XML">XML</link>,那么就应该很熟悉了):</para>
-
-          <programlisting role="template">&lt;@greet/&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  &lt;font size="+2"&gt;Hello Joe!&lt;/font&gt;
-  </programlisting>
-
-          <para>宏能做的事情还有很多,因为在 
-		  <literal>&lt;#macro <replaceable>...</replaceable>&gt;</literal> 
-		  和 <literal>&lt;/#macro&gt;</literal> 之间的东西是模板片段,也就是说它可以包含插值
-          (<literal>${<replaceable>...</replaceable>}</literal>) 和FTL标签
-          (如 <literal>&lt;#if
-          <replaceable>...</replaceable>&gt;<replaceable>...</replaceable>&lt;/#if&gt;</literal>)。</para>
-
-          <note>
-            <para>程序员通常将使用 
-			<literal>&lt;@<replaceable>...</replaceable>&gt;</literal> 这称为
-            宏 <emphasis role="term">调用</emphasis>。</para>
-          </note>
-        </section>
-
-        <section>
-          <title>参数</title>
-
-          <para>我们来改进 <literal>greet</literal> 宏使之可以使用任意的名字,
-		  而不仅仅是''Joe''。为了实现这个目的,就要使用到 
-		  <emphasis role="term">参数</emphasis>。在 <literal>macro</literal> 
-		  指令中,宏名称的后面位置是用来定义参数的。这里我们仅在 
-		  <literal>greet</literal> 宏中定义一个参数,<literal>person</literal>:</para>
-
-          <programlisting role="template">&lt;#macro greet <emphasis>person</emphasis>&gt;
-  &lt;font size="+2"&gt;Hello <emphasis>${person}</emphasis>!&lt;/font&gt;
-&lt;/#macro&gt;</programlisting>
-
-          <para>那么就可以这样来使用这个宏:</para>
-
-          <programlisting role="template">&lt;@greet <emphasis>person="Fred"</emphasis>/&gt; and &lt;@greet <emphasis>person="Batman"</emphasis>/&gt;
-</programlisting>
-
-          <para>这和HTML的语法是很相似的,将会输出:</para>
-
-          <programlisting role="output">  &lt;font size="+2"&gt;Hello <emphasis>Fred</emphasis>!&lt;/font&gt;
- and   &lt;font size="+2"&gt;Hello <emphasis>Batman</emphasis>!&lt;/font&gt;
- </programlisting>
-
-          <para>那么我们就看到了,宏参数的真实值是可以作为变量
-          (<literal>person</literal>)放在宏定义体中的。使用 <link
-          linkend="gloss.predefinedDirective">预定义指令</link>时,参数的值
-          (<literal>=</literal>号后边的值)可以是 <link 
-		  linkend="dgui_template_exp">FTL 表达式</link>。
-		  那么,不像HTML,<literal>"Fred"</literal> 
-		  和 <literal>"Batman"</literal> 引号就可以不用要了。
-		  <literal>&lt;@greet person=Fred/&gt;</literal> 也意味着使用变量的值 
-		  <literal>Fred</literal> 作为 <literal>person</literal> 参数,
-		  而不是字符串<literal>"Fred"</literal>。当然参数值并不一定是字符串类型,
-		  也可以是数字,布尔值,哈希表,序列等。也可以在 <literal>=</literal> 
-		  号左边使用复杂表达式(比如 <literal>someParam=(price + 50)*1.25</literal>)。</para>
-
-          <para>自定义指令可以有多个参数。如下所示,再添加一个新的参数 <literal>color</literal>:</para>
-
-          <programlisting role="template">&lt;#macro greet person <emphasis>color</emphasis>&gt;
-  &lt;font size="+2" color="${color}"&gt;Hello ${person}!&lt;/font&gt;
-&lt;/#macro&gt;</programlisting>
-
-          <para>那么,这个宏就可以这样来使用:</para>
-
-          <programlisting role="template">&lt;@greet person="Fred" color="black"/&gt;</programlisting>
-
-          <para>参数的顺序不重要,下面的这个和上面的含义也是相同的:</para>
-
-          <programlisting role="template">&lt;@greet color="black" person="Fred"/&gt;</programlisting>
-
-          <para>当调用这个宏的时候,只能使用在 <literal>macro</literal> 
-		  指令中定义的参数(本例中是:<literal>person</literal> 和 <literal>color</literal>)。
-		  那么当你尝试 <literal>&lt;@greet person="Fred" color="black" background="green"/&gt;</literal> 
-		  的时候就会发生错误,因为并没有在 <literal>&lt;#macro<replaceable>...</replaceable>&gt;</literal> 
-		  中提及参数 <literal>background</literal>。</para>
-
-          <para>同时也必须给出在宏中定义所有参数的值。如果尝试 
-		  <literal>&lt;@greet person="Fred"/&gt;</literal> 时也会发生错误,
-		  因为忘记指定 <literal>color</literal>的值了。
-		  很多情况下需要给一个参数指定一个相同的值,所以我们仅仅想在这个值发生变化后重新赋给变量。
-		  那么要达到这个目的,在<literal>macro</literal>指令中必须这么来指定变量:
-		  <literal><replaceable>param_name</replaceable>=<replaceable>usual_value</replaceable></literal>。
-		  例如,当没有特定值的时候,我们想要给 <literal>color</literal> 
-		  赋值为 <literal>"black"</literal>,那么 <literal>greet</literal> 
-		  指令就要这么来写:</para>
-
-          <programlisting role="template">&lt;#macro greet person color<emphasis>="black"</emphasis>&gt;
-  &lt;font size="+2" color="${color}"&gt;Hello ${person}!&lt;/font&gt;
-&lt;/#macro&gt;</programlisting>
-
-          <para>现在,我们这么使用宏就可以了:
-		  <literal>&lt;@greet person="Fred"/&gt;</literal>,因为它和
-		  <literal>&lt;@greet person="Fred" color="black"/&gt;</literal> 是相等的,
-		  这样参数 <literal>color</literal> 的值就是已知的了。
-		  如果想给 <literal>color</literal> 设置为 <literal>"red"</literal>,
-		  那么就写成: <literal>&lt;@greet person="Fred" color="red"/&gt;</literal>,
-		  这时 <literal>macro</literal> 指令就会使用这个值来覆盖之前设置的通用值,
-		  参数 <literal>color</literal> 的值就会是 <literal>"red"</literal> 了。</para>
-
-          <para>根据已知的 <link linkend="dgui_template_exp">FTL 表达式规则</link>,
-		  明白下面这一点是至关重要的。<literal>someParam=foo</literal>
-		  和 <literal>someParam="${foo}"</literal> 是不同的。第一种情况,
-		  是把变量 <literal>foo</literal> 的值作为参数的值来使用。第二种情况则是使用 <link 
-		  linkend="dgui_template_exp_stringop_interpolation">插值形式的字符串</link>,
-		  那么参数值就是字符串了,这个时候, <literal>foo</literal> 的值呈现为文本,
-		  而不管 <literal>foo</literal> 是什么类型的(数字,日期等)。看下面这个例子:
-          <literal>someParam=3/4</literal> 和 <literal>someParam="${3/4}"</literal> 是不同的。
-		  如果指令需要 <literal>someParam</literal> 是一个数字值,
-		  那么就不要用第二种方式。切记不要改变这些。</para>
-
-          <para>宏参数的另外一个重要的方面是它们是局部变量。
-		  更多局部变量的信息可以阅读:<xref linkend="dgui_misc_var"/></para>
-        </section>
-
-        <section>
-          <title>嵌套内容</title>
-
-          <para>自定义指令可以嵌套内容,和预定义指令相似:<literal>&lt;#if
-          <replaceable>...</replaceable>&gt;<replaceable>nested
-          content</replaceable>&lt;/#if&gt;</literal>。
-		  例如,下面这个例子中是创建了一个可以为嵌套的内容画出边框的宏:</para>
-
-          <programlisting role="template">&lt;#macro border&gt;
-  &lt;table border=4 cellspacing=0 cellpadding=4&gt;&lt;tr&gt;&lt;td&gt;
-    <emphasis>&lt;#nested&gt;</emphasis>
-  &lt;/tr&gt;&lt;/td&gt;&lt;/table&gt;
-&lt;/#macro&gt;</programlisting>
-
-          <para><literal>&lt;#nested&gt;</literal>
-		  指令执行位于开始和结束标记指令之间的模板代码段。
-		  如果这样写:</para>
-
-          <programlisting role="template">&lt;@border&gt;The bordered text&lt;/@border&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  &lt;table border=4 cellspacing=0 cellpadding=4&gt;&lt;tr&gt;&lt;td&gt;
-    The bordered text
-  &lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;
- </programlisting>
-
-          <para><literal>nested</literal> 指令也可以多次被调用,例如:</para>
-
-          <programlisting role="template">&lt;#macro do_thrice&gt;<emphasis>
-  &lt;#nested&gt;
-  &lt;#nested&gt;
-  &lt;#nested&gt;</emphasis>
-&lt;/#macro&gt;
-&lt;@do_thrice&gt;
-  Anything.
-&lt;/@do_thrice&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  Anything.
-  Anything.
-  Anything.</programlisting>
-
-          <para>如果不使用 <literal>nested</literal> 指令,
-		  那么嵌套的内容就不会被执行,如果不小心将
-		  <literal>greet</literal> 指令写成了这样:</para>
-
-          <programlisting role="template">&lt;@greet person="Joe"&gt;
-  Anything.
-&lt;/@greet&gt;</programlisting>
-
-          <para>FreeMarker 不会把它视为错误,只是输出:</para>
-
-          <programlisting role="output">&lt;font size="+2"&gt;Hello Joe!&lt;/font&gt;</programlisting>
-
-          <para>嵌套的内容被忽略了,因为 <literal>greet</literal> 
-		  宏没有使用 <literal>nested</literal> 指令。</para>
-
-          <para>嵌套的内容可以是任意有效的FTL,包含其他的用户自定义指令,这样也是对的:</para>
-
-          <programlisting role="template">&lt;@border&gt;
-  &lt;ul&gt;
-  &lt;@do_thrice&gt;
-    &lt;li&gt;&lt;@greet person="Joe"/&gt;
-  &lt;/@do_thrice&gt;
-  &lt;/ul&gt;
-&lt;/@border&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  &lt;table border=4 cellspacing=0 cellpadding=4&gt;&lt;tr&gt;&lt;td&gt;
-      &lt;ul&gt;
-    &lt;li&gt;&lt;font size="+2"&gt;Hello Joe!&lt;/font&gt;
-
-    &lt;li&gt;&lt;font size="+2"&gt;Hello Joe!&lt;/font&gt;
-
-    &lt;li&gt;&lt;font size="+2"&gt;Hello Joe!&lt;/font&gt;
-
-  &lt;/ul&gt;
-
-  &lt;/tr&gt;&lt;/td&gt;&lt;/table&gt;</programlisting>
-
-          <para>在嵌套的内容中,宏的 <link linkend="dgui_misc_var">局部变量</link>
-		  是不可见的。为了说明这点,我们来看:</para>
-
-          <programlisting role="template">&lt;#macro repeat count&gt;
-  &lt;#local y = "test"&gt;
-  &lt;#list 1..count as x&gt;
-    ${y} ${count}/${x}: &lt;#nested&gt;
-  &lt;/#list&gt;
-&lt;/#macro&gt;
-&lt;@repeat count=3&gt;${y!"?"} ${x!"?"} ${count!"?"}&lt;/@repeat&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">    test 3/1: ? ? ?
-    test 3/2: ? ? ?
-    test 3/3: ? ? ?</programlisting>
-
-          <para>因为 <literal>y</literal>, <literal>x</literal> 
-		  和 <literal>count</literal> 是宏的局部(私有)变量,从宏外部定义是不可见的。
-		  此外不同的局部变量的设置是为每个宏自己调用的,所以不会导致混乱:</para>
-
-          <programlisting role="template">&lt;#macro test foo&gt;${foo} (&lt;#nested&gt;) ${foo}&lt;/#macro&gt;
-&lt;@test foo="A"&gt;&lt;@test foo="B"&gt;&lt;@test foo="C"/&gt;&lt;/@test&gt;&lt;/@test&gt;
-</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">A (B (C () C) B) A</programlisting>
-        </section>
-
-        <section xml:id="dgui_misc_userdefdir_loopvar">
-          <title>宏和循环变量</title>
-
-          <indexterm>
-            <primary>loop variable</primary>
-          </indexterm>
-
-          <para>像 <literal>list</literal>这样的预定义指令可以使用循环变量;
-		  可以阅读 <xref linkend="dgui_misc_var"/> 来理解循环变量。</para>
-
-          <para>自定义指令也可以有循环变量。比如我们来扩展先前例子中的 
-		  <literal>do_thrice</literal> 指令,就可以拿到当前的循环变量的值。
-		  而对于预定义指令(如<literal>list</literal>),当调用指令时,循环变量的
-		  <emphasis>name</emphasis>是给定的(比如 <literal>&lt;#list foos as
-          foo&gt;<replaceable>...</replaceable>&lt;/#list&gt;</literal> 
-		  中的 <literal>foo</literal>),变量 <emphasis>value</emphasis> 
-		  的设置是由指令本身完成的。</para>
-
-          <programlisting role="template">&lt;#macro do_thrice&gt;
-  &lt;#nested <emphasis>1</emphasis>&gt;
-  &lt;#nested <emphasis>2</emphasis>&gt;
-  &lt;#nested <emphasis>3</emphasis>&gt;
-&lt;/#macro&gt;
-&lt;@do_thrice <emphasis>; x</emphasis>&gt; &lt;#-- user-defined directive uses ";" instead of "as" --&gt;
-  ${<emphasis>x</emphasis>} Anything.
-&lt;/@do_thrice&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  1 Anything.
-  2 Anything.
-  3 Anything.
- </programlisting>
-
-          <para>语法规则是给确定"循环"的循环变量传递真实值(比如重复嵌套内容)来作为 
-		  <literal>nested</literal> 指令的参数(当然参数可以是任意的表达式)。
-		  循环变量的名称是在自定义指令的开始标记(<literal>&lt;@...&gt;</literal>)
-		  的参数后面通过分号确定的。</para>
-
-          <para>一个宏可以使用多个循环变量(变量的顺序是很重要的):</para>
-
-          <programlisting role="template">&lt;#macro repeat count&gt;
-  &lt;#list 1..count as x&gt;
-    &lt;#nested <emphasis>x, x/2, x==count</emphasis>&gt;
-  &lt;/#list&gt;
-&lt;/#macro&gt;
-&lt;@repeat count=4 ; <emphasis>c, halfc, last</emphasis>&gt;
-  ${<emphasis>c</emphasis>}. ${<emphasis>halfc</emphasis>}&lt;#if <emphasis>last</emphasis>&gt; Last!&lt;/#if&gt;
-&lt;/@repeat&gt;</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  1. 0.5
-  2. 1
-  3. 1.5
-  4. 2 Last!
- </programlisting>
-
-          <para>在自定义指令的开始标签(分号之后)为循环变量指定不同的数字是没有问题的,
-		  而不能在 <literal>nested</literal> 指令上使用。如果在分号之后指定的循环变量少,
-		  那么就看不到 <literal>nested</literal>指令提供的最后的值,
-		  因为没有循环变量来存储这些值,下面的这些都是可以的:</para>
-
-          <programlisting role="template">&lt;@repeat count=4 ; <emphasis>c, halfc, last</emphasis>&gt;
-  ${c}. ${halfc}&lt;#if last&gt; Last!&lt;/#if&gt;
-&lt;/@repeat&gt;
-&lt;@repeat count=4 ; <emphasis>c, halfc</emphasis>&gt;
-  ${c}. ${halfc}
-&lt;/@repeat&gt;
-&lt;@repeat count=4&gt;
-  Just repeat it...
-&lt;/@repeat&gt;</programlisting>
-
-          <para>如果在分号后面指定了比 <literal>nested</literal> 指令还多的变量,
-		  那么最后的循环变量将不会被创建(在嵌套内容中不会被定义)。</para>
-        </section>
-
-        <section>
-          <title>自定义指令和宏进阶</title>
-
-          <para>现在你也许已经阅读过 FreeMarker 参考手册的相关部分了:</para>
-
-          <itemizedlist spacing="compact">
-            <listitem>
-              <para><link linkend="ref.directive.userDefined">调用自定义指令</link></para>
-            </listitem>
-
-            <listitem>
-              <para><link
-              linkend="ref.directive.macro"><literal>macro</literal>
-              指令</link></para>
-            </listitem>
-          </itemizedlist>
-
-          <para>也可以在FTL中定义方法,参见 <link 
-		  linkend="ref.directive.function"> <literal>function</literal> 指令</link>。</para>
-
-          <para>也许你对命名空间感兴趣: <xref linkend="dgui_misc_namespace"/>。
-		  命名空间可以帮助你组织和重用经常使用的宏。</para>
-        </section>
-      </section>
-
-      <section xml:id="dgui_misc_var">
-        <title>在模板中定义变量</title>
-
-        <indexterm>
-          <primary>variable</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>loop variable</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>local variable</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>temporary variable</primary>
-        </indexterm>
-
-        <para>正如我们已经描述过的,模板可以使用在数据模型中定义的变量。
-		在数据模型之外,模板本身也可以定义变量来使用。
-		这些临时变量可以使用FTL指令来创建和替换。请注意每一次的 <link 
-		linkend="gloss.templateProcessingJob">模板执行</link> 工作都维护它自己的私有变量,
-		同时来渲染页面。变量的初始值是空,当模板执行工作结束这些变量便被销毁了。</para>
-
-        <para>可以访问一个在模板里定义的变量,就像是访问数据模型根root上的变量一样。
-		这个变量比定义在数据模型中的同名参数有更高的优先级,也就是说,
-		如果恰巧定义了一个名为''foo''的变量,而在数据模型中也有一个名为''foo''的变量,
-		那么模板中的变量就会将数据模型根上的变量隐藏(而不是覆盖!)。
-		例如,<literal>${foo}</literal> 将会输出在模板中定义的变量。</para>
-
-        <para>在模板中可以定义三种类型的变量:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para><emphasis role="term">''简单''变量</emphasis>:
-			它能从模板中的任何位置来访问,或者从使用 <literal>include</literal> 
-			指令引入的模板访问。可以使用 <link 
-			linkend="ref.directive.assign"><literal>assign</literal></link> 
-			指令来创建或替换这些变量。因为宏和方法只是变量,那么 <link 
-			linkend="ref.directive.macro"><literal>macro</literal> 指令 </link> 
-			和 <link linkend="ref.directive.function"><literal>function</literal> 指令</link> 
-			也可以用来设置变量,就像 <literal>assign</literal> 那样。</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">局部变量</emphasis>:它们只能被设置在
-            <link linkend="gloss.macroDefinitionBody">宏定义体</link>内,
-			而且只在宏内可见。一个局部变量的生命周期只是宏的调用过程。可以使用
-			<link linkend="ref.directive.local"><literal>local</literal>指令</link>
-			在宏定义体内创建或替换局部变量。</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">循环变量</emphasis>:循环变量是由如
-			<link linkend="ref.directive.list"><literal>list</literal></link>
-			指令自动创建的,而且它们只在指令的开始和结束标记内有效。<link 
-			linkend="ref.directive.macro">宏</link> 的参数是局部变量而不是循环变量。</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="term">全局变量</emphasis>:这是一个高级话题了,
-			并且这种变量最好别用。即便它们属于不同的命名空间,
-			全局变量也被所有模板共享,因为它们是被 <link 
-			linkend="ref.directive.import"><literal>import</literal>进来的</link>,
-			不同于 <literal>include</literal> 进来的。那么它们的可见度就像数据模型那样。
-			全局变量通过 <link 
-			linkend="ref.directive.global"><literal>global</literal>指令</link>来定义。</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>示例:使用 <literal>assign</literal> 创建和替换变量:</para>
-
-        <programlisting role="template">&lt;#assign x = 1&gt;  &lt;#-- create variable x --&gt;
-${x}
-&lt;#assign x = x + 3&gt; &lt;#-- replace variable x --&gt;
-${x}</programlisting>
-
-        <para>输出为:</para>
-
-        <programlisting role="output">1
-4</programlisting>
-
-        <para>局部变量也会隐藏(不是覆盖)同名的''简单''变量。
-		循环变量也会隐藏(不是覆盖)同名的''简单''变量。例如:</para>
-
-        <programlisting role="template">&lt;#assign x = "plain"&gt;
-1. ${x}  &lt;#-- we see the plain var. here --&gt;
-&lt;@test/&gt;
-6. ${x}  &lt;#-- the value of plain var. was not changed --&gt;
-&lt;#list ["loop"] as x&gt;
-    7. ${x}  &lt;#-- now the loop var. hides the plain var. --&gt;
-    &lt;#assign x = "plain2"&gt; &lt;#-- replace the plain var, hiding does not mater here --&gt;
-    8. ${x}  &lt;#-- it still hides the plain var. --&gt;
-&lt;/#list&gt;
-9. ${x}  &lt;#-- the new value of plain var. --&gt;
-
-&lt;#macro test&gt;
-  2. ${x}  &lt;#-- we still see the plain var. here --&gt;
-  &lt;#local x = "local"&gt;
-  3. ${x}  &lt;#-- now the local var. hides it --&gt;
-  &lt;#list ["loop"] as x&gt;
-    4. ${x}  &lt;#-- now the loop var. hides the local var. --&gt;
-  &lt;/#list&gt;
-  5. ${x}  &lt;#-- now we see the local var. again --&gt;
-&lt;/#macro&gt;</programlisting>
-
-        <para>输出为:</para>
-
-        <programlisting role="output">1. plain
-  2. plain
-  3. local
-    4. loop
-  5. local
-6. plain
-    7. loop
-    8. loop
-9. plain2
- </programlisting>
-
-        <para>内部循环变量可以隐藏外部循环变量:</para>
-
-        <programlisting role="template">&lt;#list ["loop 1"] as x&gt;
-  ${x}
-  &lt;#list ["loop 2"] as x&gt;
-    ${x}
-    &lt;#list ["loop 3"] as x&gt;
-      ${x}
-    &lt;/#list&gt;
-    ${x}
-  &lt;/#list&gt;
-  ${x}
-&lt;/#list&gt;</programlisting>
-
-        <para>输出为:</para>
-
-        <programlisting role="output">  loop 1
-    loop 2
-      loop 3
-    loop 2
-  loop 1</programlisting>
-
-        <para>请注意,循环变量的设置是通过指令调用时创建的(本例中的
-		<literal>&lt;list <replaceable>...</replaceable>&gt;</literal> 标签)。
-		没有其他的方式去改变循环变量的值(也就是说,不能使用定义指令来改变它的值)。
-		从上面的示例来看,也可以使用一个循环变量来暂时隐藏另外一个。</para>
-
-        <para>有时会发生一个变量隐藏数据模型中的同名变量,
-		但是如果想访问数据模型中的变量,此时就可以使用 <link 
-		linkend="dgui_template_exp_var_special">特殊变量</link> 
-		<literal>globals</literal>。例如,假设我们在数据模型中有一个名为 
-		<literal>user</literal> 的变量,值为''Big Joe'':</para>
-
-        <programlisting role="template">&lt;#assign user = "Joe Hider"&gt;
-${user}          &lt;#-- prints: Joe Hider --&gt;
-${.globals.user} &lt;#-- prints: Big Joe --&gt;</programlisting>
-
-        <para>通过 <link linkend="ref.directive.global"><literal>global</literal>指令</link> 
-		设置的变量可以隐藏数据模型中的同名变量。通常,全局变量的设置会有精确的目的。
-		但仍然可以使用如下方式来访问数据模型变量:<literal>.data_model.user</literal>。</para>
-
-        <para>想了解更多的变量使用语法,请阅读: <xref linkend="dgui_template_exp"/></para>
-      </section>
-
-      <section xml:id="dgui_misc_namespace">
-        <title>命名空间</title>
-
-        <indexterm>
-          <primary>namespaces</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>libraries</primary>
-        </indexterm>
-
-        <para>当运行FTL模板时,就会有使用 <literal>assign</literal> 
-		和 <literal>macro</literal> 指令创建的变量的集合(可能是空的),
-		可以从 <link linkend="dgui_misc_var">前一章</link> 来看如何使用它们。
-		像这样的变量集合被称为  <emphasis role="term">命名空间</emphasis>。
-		简单的情况下可以只使用一个命名空间,称之为 
-		<emphasis role="term">主命名空间</emphasis>。因为通常只使用该命名空间,
-		所以就没有意识到这点。</para>
-
-        <para>如果想创建可以重复使用的宏,函数和其他变量的集合,
-		通常用术语来说就是引用 <emphasis role="term">库</emphasis>。
-		使用多个命名空间是必然的。只要考虑你在一些项目中,
-		或者想和他人共享使用的时候,你是否有一个很大的宏的集合。
-		但要确保库中没有宏(或其他变量)名和数据模型中变量同名,
-		而且也不能和模板中引用其他库中的变量同名是不可能的。
-		通常来说,变量因为名称冲突时也会相互冲突。
-		所以要为每个库中的变量使用不同的命名空间。</para>
-
-        <section>
-          <title>创建一个库</title>
-
-          <para>我们来建立一个简单的库。假设你需要通用的变量 
-		  <literal>copyright</literal> 和 <literal>mail</literal>
-		  (在你有疑问之前,宏 <emphasis>当作是</emphasis> 变量):</para>
-
-          <programlisting role="template">&lt;#macro copyright date&gt;
-  &lt;p&gt;Copyright (C) ${date} Julia Smith. All rights reserved.&lt;/p&gt;
-&lt;/#macro&gt;
-
-&lt;#assign mail = "jsmith@acme.com"&gt;</programlisting>
-
-          <para>把上面的这些定义存储在文件 <literal>lib/my_test.ftl</literal> 中
-		  (目录是存放模板的位置)。假设想在 <literal>aWebPage.ftl</literal> 
-		  中使用这个模板。如果在 <literal>aWebPage.ftl</literal> 中使用 
-		  <literal>&lt;#include "/lib/my_test.ftl"&gt;</literal>,
-		  那么就会在主命名空间中创建两个变量,这样就不是很好,
-		  因为想让它们只在同一个命名空间''My Test Library''中。所以就不得不使用 <link 
-		  linkend="ref.directive.import"><literal>import</literal>指令</link>
-		  来代替 <literal>include</literal> 了。乍一看,这个指令和 
-		  <literal>include</literal> 很相似,但是它会为 <literal>lib/my_test.ftl</literal> 
-		  创建一个空的命名空间,然后在那里执行。<literal>lib/my_test.ftl</literal> 
-		  会发现它自己在一个新的环境中,那里只有数据模型的变量可以找到
-		  (因为它们在哪儿都是可见的),然后会在这个环境中创建两个变量。现在来看这很不错,
-		  但是如果想访问 <literal>aWebPage.ftl</literal> 中的两个变量,
-		  而它们使用的是主命名空间,就不能看到其他命名空间中的变量。
-		  解决方法是 <literal>import</literal> 指令不仅仅创建命名空间,而且要通过 
-		  <literal>import</literal> 的调用者(本例中的主命名空间)创建一个新的哈希表变量,
-		  这就成为进入新的命名空间的大门。那么 
-		  <literal>aWebPage.ftl</literal> 就像下面这样:</para>
-
-          <programlisting role="template">&lt;#import "/lib/my_test.ftl" as <emphasis>my</emphasis>&gt; &lt;#-- the hash called "my" will be the "gate" --&gt;
-&lt;@<emphasis>my</emphasis>.copyright date="1999-2002"/&gt;
-${<emphasis>my</emphasis>.mail}</programlisting>
-
-          <para>要注意它是怎么访问为 <literal>/lib/my_test.ftl</literal> 
-		  创建的命名空间中的变量的,使用新创建的命名空间访问哈希表,
-		  <literal>my</literal>。将会输出:</para>
-
-          <programlisting role="output">  &lt;p&gt;Copyright (C) 1999-2002 Julia Smith. All rights reserved.&lt;/p&gt;
-jsmith@acme.com</programlisting>
-
-          <para>如果在主命名空间中有一个变量,名为 <literal>mail</literal> 
-		  或 <literal>copyright</literal>,那么就不会引起混乱了,
-		  因为两个模板使用了不同的命名空间。例如,在 <literal>lib/my_test.ftl</literal> 
-		  中修改 <literal>copyright</literal> 成如下这样:</para>
-
-          <programlisting role="template">&lt;#macro copyright date&gt;
-  &lt;p&gt;Copyright (C) ${date} Julia Smith. All rights reserved.
-  &lt;br&gt;Email: <emphasis>${mail}</emphasis>&lt;/p&gt;
-&lt;/#macro&gt;</programlisting>
-
-          <para>然后替换 <literal>aWebPage.ftl</literal> 中的内容:</para>
-
-          <programlisting role="template">&lt;#import "/lib/my_test.ftl" as my&gt;
-<emphasis>&lt;#assign mail="fred@acme.com"&gt;</emphasis>
-&lt;@my.copyright date="1999-2002"/&gt;
-${my.mail}
-${mail}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  &lt;p&gt;Copyright (C) 1999-2002 Julia Smith. All rights reserved.
-  &lt;br&gt;Email: <emphasis>jsmith@acme.com</emphasis>&lt;/p&gt;
-jsmith@acme.com
-fred@acme.com</programlisting>
-
-          <para>当调用了 <literal>copyright</literal> 宏之后,输出和上面的是相似的,
-		  因为 FreeMarker 已经暂时转向由 <literal>import</literal> 指令为 
-		  <literal>/lib/my_test.ftl</literal> 生成的命名空间了。因此,
-		  <literal>copyright</literal> 宏看到这里存在的变量 <literal>mail</literal>,
-		  而不是主命名空间中存在的其它 <literal>mail</literal></para>
-        </section>
-
-        <section>
-          <title>在引入的命名空间中编写变量</title>
-
-          <para>偶尔想要在一个被包含的命名空间上创建或替换一个变量。
-		  那么可以使用 <literal>assign</literal> 指令,
-		  如果用到了它的 <literal>namespace</literal> 变量,例如下面这样:</para>
-
-          <programlisting role="template">&lt;#import "/lib/my_test.ftl" as my&gt;
-${my.mail}
-&lt;#assign mail="jsmith@other.com" <emphasis>in my</emphasis>&gt;
-${my.mail}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">jsmith@acme.com
-jsmith@other.com</programlisting>
-        </section>
-
-        <section>
-          <title>命名空间和数据模型</title>
-
-          <para>数据模型中的变量在任何位置都是可见的。例如,
-		  如果在数据模型中有一个名为 <literal>user</literal> 
-		  的变量,那么 <literal>lib/my_test.ftl</literal> 也能访问它,
-		  <literal>aWebPage.ftl</literal> 当然也能:</para>
-
-          <programlisting role="template">&lt;#macro copyright date&gt;
-  &lt;p&gt;Copyright (C) ${date} <emphasis>${user}</emphasis>. All rights reserved.&lt;/p&gt;
-&lt;/#macro&gt;
-
-&lt;#assign mail = "<emphasis>${user}</emphasis>@acme.com"&gt;</programlisting>
-
-          <para>如果 <literal>user</literal> 是 ''Fred''的话,下面这个例子:</para>
-
-          <programlisting role="template">&lt;#import "/lib/my_test.ftl" as my&gt;
-&lt;@my.copyright date="1999-2002"/&gt;
-${my.mail}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  &lt;p&gt;Copyright (C) 1999-2002 Fred. All rights reserved.&lt;/p&gt;
-Fred@acme.com</programlisting>
-
-          <para>不要忘了在模板的命名空间(可以使用 <literal>assign</literal> 
-		  或 <literal>macro</literal> 指令来创建的变量)
-		  中的变量有着比数据模型中的变量更高的优先级。因此,
-		  数据模型的内容不会干涉到由库创建的变量。</para>
-
-          <note>
-            <para>在一些不寻常的应用中,也许想在模板中创建所有命名空间都可见的变量,
-			就像数据模型中的变量一样。但是你不能在模板中改变数据模型,
-			却可以通过 <literal>global</literal> 指令来达到相似的效果,
-			可以阅读 <link linkend="ref.directive.global">参考手册</link> 来获得更多信息。</para>
-          </note>
-        </section>
-
-        <section>
-          <title>命名空间的生命周期</title>
-
-          <para>命名空间由使用 <literal>import</literal> 指令中所写的路径来识别。
-		  如果想多次 <literal>import</literal> 这个路径,那么只会为第一次 
-		  <literal>import</literal> 引用创建命名空间并执行模板。后面相同路径的 
-		  <literal>import</literal> 只是创建一个哈希表当作访问相同命名空间的“门”。
-		  例如,在 <literal>aWebPage.ftl</literal> 中:</para>
-
-          <programlisting role="template">&lt;#import "/lib/my_test.ftl" as my&gt;
-&lt;#import "/lib/my_test.ftl" as foo&gt;
-&lt;#import "/lib/my_test.ftl" as bar&gt;
-${my.mail}, ${foo.mail}, ${bar.mail}
-&lt;#assign mail="jsmith@other.com" in my&gt;
-${my.mail}, ${foo.mail}, ${bar.mail}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">jsmith@acme.com, jsmith@acme.com, jsmith@acme.com
-jsmith@other.com, jsmith@other.com, jsmith@other.com</programlisting>
-
-          <para>这里可以看到通过 <literal>my</literal>, <literal>foo</literal> 
-		  和 <literal>bar</literal> 访问相同的命名空间。</para>
-
-          <para>请注意,命名空间是不分层次的,它们相互之间是独立存在的。
-		  那么,如果在命名空间N1中 <literal>import</literal> 命名空间N2,
-		  那N2也不在N1中,N1只是可以通过哈希表来访问N2。这和在主命名空间中 
-		  <literal>import</literal> N2,然后直接访问命名空间N2是一样的过程。</para>
-
-          <para>每一次 <link linkend="gloss.templateProcessingJob">模板的执行过程</link>,
-		  它都有一个私有的命名空间的集合。每一次模板执行工作都是一个分离且有序的过程,
-		  它们仅仅存在一段很短的时间,同时页面用以渲染内容,
-		  然后就和所有填充过的命名空间一起消失了。因此,无论何时我们说第一次调用 
-		  <literal>import</literal>,一个单一模板执行工作的内容都是这样。</para>
-        </section>
-
-        <section>
-          <title>为他人编写库</title>
-
-          <indexterm>
-            <primary>library path</primary>
-          </indexterm>
-
-          <para>如果你已经为其他人员编写一个有用的,高质量的库,你也许想把它放在网络上
-          (就像 <link 
-		  xlink:href="https://freemarker.apache.org/libraries.html">https://freemarker.apache.org/libraries.html</link>)。
-		  为了防止和其他作者使用库的命名相冲突,而且引入其他库时要书写简单,
-		  这有一个事实上的标准,那就是指定库路径的格式。这个标准是:
-		  库的路径必须对模板和其他库可用(可引用),就像这样:</para>
-
-          <para><literal>/lib/<replaceable>yourcompany.com</replaceable>/<replaceable>your_library</replaceable>.ftl</literal></para>
-
-          <para>如果你为Example公司工作,它们拥有www.example.com网的主页,
-		  你的工作是开发一个部件库,那么要引入你所写的FTL的路径应该是:</para>
-
-          <para><literal>/lib/example.com/widget.ftl</literal></para>
-
-          <para>请注意,www已经被省略了。第三次路径分割后的部分可以包含子目录,可以像下面这样写:</para>
-
-          <para><literal>/lib/example.com/commons/string.ftl</literal></para>
-
-          <para>一个重要的规则就是路径不应该包含大写字母,为了分隔词语,
-		  使用下划线 <literal>_</literal>,就像 <literal>wml_form</literal>
-		  (而不是 <literal>wmlForm</literal> )。</para>
-
-          <para>请注意,如果你的工作不是为公司或组织开发库,你应该使用项目主页的URL,比如
-		  <literal>/lib/example.sourceforge.net/example.ftl</literal>,或
-          <literal>/lib/geocities.com/jsmith/example.ftl</literal>。</para>
-        </section>
-      </section>
-
-      <section xml:id="dgui_misc_whitespace">
-        <title>空白处理</title>
-
-        <indexterm>
-          <primary>white-space removal</primary>
-        </indexterm>
-
-        <para>在运行中,模板中的 <link linkend="gloss.whiteSpace">空白</link> 
-		处理在某种程度上来说是纠缠所有模板引擎的一个问题。</para>
-
-        <para>我们来看这个模板。我已经用颜色标记了模板中的组件:
-		<phrase role="markedText">文本</phrase>,
-		<phrase role="markedInterpolation">插值</phrase>,
-		<phrase role="markedFTLTag">FTL 标签</phrase>.。
-		使用 <phrase role="markedInvisibleText">[BR]</phrase> 来想象 
-		<link linkend="gloss.lineBreak">换行</link>。</para>
-
-        <programlisting role="template"><phrase role="markedText">&lt;p&gt;List of users:<phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedFTLTag">&lt;#assign users = [{"name":"Joe",        "hidden":false},<phrase
-                role="markedInvisibleText">[BR]</phrase>
-                  {"name":"James Bond", "hidden":true},<phrase
-                role="markedInvisibleText">[BR]</phrase>
-                  {"name":"Julia",      "hidden":false}]&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-&lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedFTLTag">&lt;#list users as user&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedFTLTag">&lt;#if !user.hidden&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  &lt;li&gt;<phrase role="markedInterpolation">${user.name}</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedFTLTag">&lt;/#if&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedFTLTag">&lt;/#list&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-&lt;/ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;p&gt;That's all.</phrase></programlisting>
-
-        <para>如果 FreeMarker 能按照规则输出所有的 
-		<phrase role="markedText">文本</phrase>,那将会输出:</para>
-
-        <programlisting role="output"><phrase role="markedText">&lt;p&gt;List of users:<phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedInvisibleText">[BR]</phrase>
-  &lt;li&gt;</phrase>Joe<phrase role="markedText"><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedInvisibleText">[BR]</phrase>  
-  &lt;li&gt;</phrase>Julia<phrase role="markedText"><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;/ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;p&gt;That's all.</phrase></programlisting>
-
-        <para>这里有太多的不想要的空格和换行了。幸运的是,HTML和XML对空白都不是敏感的,
-		但是这么多多余的空白是很令人头疼的,而且处理后的HTML文件大小增加也是没必要的。
-		当然,对于空白敏感方式的输出这依旧是个大问题。</para>
-
-        <para>FreeMarker 提供下面的工具来处理这个问题:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>忽略某些模板文件的空白的工具
-			<phrase role="forProgrammers">(解析阶段空白就被移除了)</phrase>:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>剥离空白:这个特性会自动忽略在FTL标签周围多余的空白。
-				这个特性可以通过模板来随时启用和禁用。</para>
-              </listitem>
-
-              <listitem>
-                <para>微调指令:<literal>t</literal>,<literal>rt</literal>, 
-				<literal>lt</literal>。使用这些指令可以明确地告诉 FreeMarker 去忽略某些空白。
-				可以阅读 <link linkend="ref.directive.t">参考手册</link> 来获取更多信息。</para>
-              </listitem>
-
-              <listitem>
-                <para><link linkend="ref.directive.ftl"><literal>ftl</literal></link> 参数 
-				<literal>strip_text</literal>:这将从模板中删除所有顶级文本。
-				对于只包含定义宏的模板来说很有用(还有其它一些没有输出的指令),
-				因为它可以移除宏定义和其他顶级指令中的换行符,
-				这样可以提高模板的可读性。</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-
-          <listitem>
-            <para>从输出中移除空白的工具 
-			<phrase role="forProgrammers">(移除临近的空白)</phrase>:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para><literal>compress</literal> 指令。</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-        </itemizedlist>
-
-        <section xml:id="dgui_misc_whitespace_stripping">
-          <title>剥离空白</title>
-
-          <indexterm>
-            <primary>white-space removal</primary>
-
-            <secondary>stripping</secondary>
-          </indexterm>
-
-          <para>如果对模板开启这个特性,那么它就会自动忽略
-		  (也就是不在输出中打印出来)两种典型的多余空白:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para>缩进空白和在行末尾的尾部空白(包括换行符)在只包含FTL标签的行中会被忽略
-			  (比如 <literal>&lt;@myMacro/&gt;</literal>, <literal>&lt;#if
-              <replaceable>...</replaceable>&gt;</literal>)和FTL注释(如 <literal>&lt;#-- blah --&gt;</literal>),
-			  除了被忽略的空白本身。例如,如果一行只包含一个<literal>&lt;#if
-              <replaceable>...</replaceable>&gt;</literal>,
-			  那么在标签前面的缩进和标签后面的换行符将会被忽略。
-			  但是,如果这行上包含<literal>&lt;#if <replaceable>...</replaceable>&gt;x</literal>,
-			  那么空白就不会被忽略,因为这个<literal>x</literal>不是FTL标签。请注意,根据这些规则,
-			  一行上包含<literal>&lt;#if <replaceable>...</replaceable>&gt;&lt;#list
-              <replaceable>...</replaceable>&gt;</literal>,空白就会被忽略,
-			  而一行上有<literal>&lt;#if <replaceable>...</replaceable>&gt; &lt;#list
-              <replaceable>...</replaceable>&gt;</literal>这样的就不会,
-			  因为在两个FTL标签之间的空白是嵌入的空白,而不是缩进的或尾部空白。</para>
-            </listitem>
-
-            <listitem>
-              <para>加在下面这些指令之间的空白会被忽略:<literal>macro</literal>,
-			  <literal>function</literal>,<literal>assign</literal>, 
-			  <literal>global</literal>,<literal>local</literal>, 
-			  <literal>ftl</literal>, <literal>import</literal>,
-			  但也是指令之间<emphasis>仅仅</emphasis>只有一个空白或FTL注释。实际应用中,
-			  它意味着你可以在宏定义和参数定义之间放置空行,因为行间距是为了更好的可读性,
-			  不包括在输出中打印不必要的空行(换行符)。</para>
-            </listitem>
-          </itemizedlist>
-
-          <para>使用了剥离空白后,上面那个例子中的输出就会是:</para>
-
-          <programlisting role="output"><phrase role="markedText">&lt;p&gt;List of users:<phrase
-                role="markedInvisibleText">[BR]</phrase>
-&lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-  &lt;li&gt;</phrase>Joe<phrase role="markedText"><phrase
-                role="markedInvisibleText">[BR]</phrase>
-  &lt;li&gt;</phrase>Julia<phrase role="markedText"><phrase
-                role="markedInvisibleText">[BR]</phrase>
-&lt;/ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;p&gt;That's all.</phrase></programlisting>
-
-          <para>这是因为在剥离之后,模板就变成这样了,被忽略的文本没有被<phrase 
-		  role="markedText">标色</phrase>:</para>
-
-          <programlisting role="template"><phrase role="markedText">&lt;p&gt;List of users:<phrase
-                role="markedInvisibleText">[BR]</phrase></phrase>
-<phrase role="markedFTLTag">&lt;#assign users = [{"name":"Joe",        "hidden":false},<phrase
-                role="markedInvisibleText">[BR]</phrase>
-                  {"name":"James Bond", "hidden":true},<phrase
-                role="markedInvisibleText">[BR]</phrase>
-                  {"name":"Julia",      "hidden":false}]&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedText">&lt;ul&gt;<phrase role="markedInvisibleText">[BR]</phrase></phrase>
-<phrase role="markedFTLTag">&lt;#list users as user&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-  <phrase role="markedFTLTag">&lt;#if !user.hidden&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedText">  &lt;li&gt;<phrase role="markedInterpolation">${user.name}</phrase><phrase
-                role="markedInvisibleText">[BR]</phrase></phrase>
-  <phrase role="markedFTLTag">&lt;/#if&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedFTLTag">&lt;/#list&gt;</phrase><phrase
-              role="markedInvisibleText">[BR]</phrase>
-<phrase role="markedText">&lt;/ul&gt;<phrase role="markedInvisibleText">[BR]</phrase>
-&lt;p&gt;That's all.</phrase></programlisting>
-
-          <para>剥离空白功能可以通过 <link 
-		  linkend="ref.directive.ftl"><literal>ftl</literal> 指令</link>
-		  在模板中开启或关闭。如果你没有通过 <literal>ftl</literal> 指令来指定,
-		  那么剥离空白功能是开启还是关闭就依据程序员是如何设置 FreeMarker 的了。
-		  默认的情况下剥离空白是开启的,程序员可以留着不管(<phrase 
-		  role="forProgrammers">建议这样做</phrase>)。<phrase 
-		  role="forProgrammers">请注意开启剥离空白时 <emphasis>不会</emphasis> 
-		  降低模板执行的效率,剥离空白的操作在模板加载时就已经完成了。</phrase></para>
-
-          <para>剥离空白可以为单独的一行关闭,就是使用<link 
-		  linkend="ref.directive.nt"><literal>nt</literal></link>
-		  指令(对没有去掉空白的行来说)。</para>
-        </section>
-
-        <section>
-          <title>使用compress指令</title>
-
-          <indexterm>
-            <primary>white-space removal</primary>
-
-            <secondary>compress</secondary>
-          </indexterm>
-
-          <para>另外一种方法就是使用<link 
-		  linkend="ref.directive.compress"><literal>compress</literal>
-          指令</link>。和剥离空白相反,这个工作是直接基于生成的输出内容,
-		  而不是对于模板进行。也就是说,它会动态地检查输出内容,
-		  而不会检查生成输出FTL的程序。它会很强势地移除缩进,
-		  空行和重复的空格/制表符(可以阅读<link 
-		  linkend="ref.directive.compress">参考手册</link>
-		  部分来获取更多信息)。所以对于下面这段代码:</para>
-
-          <programlisting role="template"><emphasis>&lt;#compress&gt;</emphasis>
-&lt;#assign users = [{"name":"Joe",        "hidden":false},
-                  {"name":"James Bond", "hidden":true},
-                  {"name":"Julia",      "hidden":false}]&gt;
-List of users:
-&lt;#list users as user&gt;
-  &lt;#if !user.hidden&gt;
-  - ${user.name}
-  &lt;/#if&gt;
-&lt;/#list&gt;
-That's all.
-<emphasis>&lt;/#compress&gt;</emphasis></programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">List of users:
-- Joe
-- Julia
-That's all.</programlisting>
-
-          <para>请注意 <literal>compress</literal> 是完全独立于剥离空白特性的。
-		  所以它剥离模板中的空白是可能的,那么之后输出的内容就是被 
-		  <literal>压缩</literal> 过的。</para>
-
-          <para>此外,在默认情况下,名为 <literal>compress</literal> 
-		  的用户自定义指令是可以在数据模型中存在的(由于向下兼容特性)。
-		  这和指令是相同的,除了可以选择设置 <literal>single_line</literal> 参数,
-		  这将会移除所有的介于其中的换行符。在最后那个例子中,如果使用<literal>&lt;@compress
-          single_line=true&gt;<replaceable>...</replaceable>&lt;/@compress&gt;</literal>
-		  来代替<literal>&lt;#compress&gt;<replaceable>...</replaceable>&lt;/#compress&gt;</literal>,
-		  那么就会得到如下输出:</para>
-
-          <programlisting role="output">List of users: - Joe - Julia That's all.</programlisting>
-        </section>
-      </section>
-
-      <section xml:id="dgui_misc_alternativesyntax">
-        <title>替换(方括号)语法</title>
-
-        <indexterm>
-          <primary>alternative syntax</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>square bracket syntax</primary>
-        </indexterm>
-
-        <note>
-          <para>这个特性从 FreeMarker 2.3.4 版本后才存在。</para>
-        </note>
-
-        <para>FreeMarker支持一个替换的语法。就是在FreeMarker的指令和注释中用 
-		<literal>[</literal> 和 <literal>]</literal> 来代替 
-		<literal>&lt;</literal> 和 <literal>&gt;</literal>,例如下面这个例子:</para>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para>调用预定义指令:<literal>[#list animals as
-            animal]<replaceable>...</replaceable>[/#list]</literal></para>
-          </listitem>
-
-          <listitem>
-            <para>调用自定义指令:<literal>[@myMacro
-            /]</literal></para>
-          </listitem>
-
-          <listitem>
-            <para>注释:<literal>[#-- the comment --]</literal></para>
-          </listitem>
-        </itemizedlist>
-
-        <para>为了使用这种语法从而代替默认语法,从模板开始,使用 <link 
-		linkend="ref_directive_ftl"><literal>ftl</literal> 指令</link> 都要使用这用语法。
-		如果你不知道什么是 <literal>ftl</literal> 指令,那么就用
-		<literal>[#ftl]</literal> 来开始模板,要记住这个要放在文件的最前面(除了<link 
-		linkend="gloss.whiteSpace">white-space</link>可以在它前面)。
-		例如,下面的示例是 <link linkend="dgui_quickstart_template">入门</link> 
-		章节的最后一个例子使用这种替换语法的样子(假设这是一个完整的模板,而不是一个片段):</para>
-
-        <programlisting role="template"><emphasis>[#ftl]</emphasis>
-&lt;p&gt;We have these animals:
-&lt;table border=1&gt;
-  &lt;tr&gt;&lt;th&gt;Name&lt;th&gt;Price
-  <emphasis>[#list animals as animal]</emphasis>
-  &lt;tr&gt;
-    &lt;td&gt;
-      <emphasis>[#if animal.size == "large"]</emphasis>&lt;b&gt;<emphasis>[/#if]</emphasis>
-      ${animal.name}
-      <emphasis>[#if animal.size == "large"]</emphasis>&lt;/b&gt;<emphasis>[/#if]</emphasis>
-    &lt;td&gt;${animal.price} Euros
-  <emphasis>[/#list]</emphasis>
-&lt;/table&gt;</programlisting>
-
-        <para>这种替换语法(方括号)和默认语法(尖括号)在一个模板中是相互排斥的。
-		那就是说,整个模板要么全部使用替换语法,要么全部使用默认语法。
-		如果模板使用了替换语法,那么如 <literal>&lt;#if <replaceable>...</replaceable>&gt;</literal> 
-		这样的部分就会被算作是静态文本,而不是FTL标签了。类似地,如果模板使用默认语法,
-		那么如 <literal>[#if <replaceable>...</replaceable>]</literal> 这样的也会被算作是静态文本,
-		而不是FTL标签。</para>
-
-        <para>如果你以<literal>[#ftl <replaceable>...</replaceable>]</literal>
-		(<literal><replaceable>...</replaceable></literal> 代表可选的参数列表,
-		当然仅用 <literal>[#ftl]</literal> 也行)来开始文件,那文件就会使用替换(方括号)语法。
-		如果使用 <literal>&lt;#ftl <replaceable>...</replaceable>&gt;</literal> 来开始,
-		那么文件就会使用正常(尖括号)语法。如果文件中没有 <literal>ftl</literal> 指令,
-		那么程序员可以通过配置FreeMarker <phrase role="forProgrammers">
-		(程序员可以参看 javadoc API 文档中的 
-		<literal>Configuration.setTagSyntax(int)</literal>)</phrase> 来决定使用哪种语法。
-		但是大多数情况,程序员可能使用默认配置。FreeMarker 2.3.x 版本默认配置使用常规语法。
-		而2.4版本中的默认配置将会自动检测,也就是说第一个FreeMarker标签决定了语法形式
-		(它可以是任意的,而不仅仅是<literal>ftl</literal>)。</para>
-      </section>
-    </chapter>
-  </part>
-
-  <part xml:id="pgui">
-    <title>程序开发指南</title>
-
-    <chapter xml:id="pgui_quickstart">
-      <title>入门</title>
-
-      <para>如果你还是使用FreeMarker的新手,在开始本章之前,
-	  你应该先阅读 <xref linkend="dgui_quickstart_basics"/>。</para>
-
-      <section xml:id="pgui_quickstart_createconfiguration">
-        <title>创建 Configuration 实例</title>
-
-        <indexterm>
-          <primary>configuration</primary>
-        </indexterm>
-
-        <para>首先,你应该创建一个 <literal>freemarker.template.Configuration</literal> 实例,
-		然后调整它的设置。<literal>Configuration</literal> 
-		实例是存储 FreeMarker 应用级设置的核心部分。同时,它也处理创建和 
-		<emphasis>缓存</emphasis> 预解析模板(比如 <literal>Template</literal> 对象)的工作。</para>
-
-        <para>也许你只在应用(可能是servlet)生命周期的开始<emphasis>执行一次</emphasis>:</para>
-
-        <programlisting role="unspecified">// Create your Configuration instance, and specify if up to what FreeMarker
-// version (here 2.3.22) do you want to apply the fixes that are not 100%
-// backward-compatible. See the Configuration JavaDoc for details.
-Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
-
-// Specify the source where the template files come from. Here I set a
-// plain directory for it, but non-file-system sources are possible too:
-cfg.setDirectoryForTemplateLoading(new File("<replaceable>/where/you/store/templates</replaceable>"));
-
-// Set the preferred charset template files are stored in. UTF-8 is
-// a good choice in most applications:
-cfg.setDefaultEncoding("UTF-8");
-
-// Sets how errors will appear.
-// During web page *development* TemplateExceptionHandler.HTML_DEBUG_HANDLER is better.
-cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);</programlisting>
-
-        <para>从现在开始,应该使用 <emphasis>单</emphasis> 实例配置(也就是说,它是单例的)。
-		请注意不管一个系统有多少独立的组件来使用 FreeMarker,
-		它们都会使用他们自己私有的 <literal>Configuration</literal> 实例。</para>
-
-        <warning>
-          <para>不需要重复创建 <literal>Configuration</literal> 实例;
-		  它的代价很高,尤其是会丢失缓存。<literal>Configuration</literal> 
-		  实例就是应用级别的单例。</para>
-        </warning>
-
-        <para>当使用多线程应用程序(比如Web网站),<literal>Configuration</literal> 
-		实例中的设置就不能被修改。它们可以被视作为 <quote>有效的不可改变的</quote> 
-		对象, 也可以继续使用 <emphasis>安全发布</emphasis> 技术
-		(参考 JSR 133 和相关的文献)来保证实例对其它线程也可用。比如,
-		通过final或volatile字段来声明实例,或者通过线程安全的IoC容器,但不能作为普通字段。
-        (<literal>Configuration</literal> 中不处理修改设置的方法是线程安全的。)</para>
-      </section>
-
-      <section xml:id="pgui_quickstart_createdatamodel">
-        <title>创建数据模型</title>
-
-        <indexterm>
-          <primary>data-model</primary>
-
-          <secondary>assembling with Java</secondary>
-        </indexterm>
-
-        <para>在简单的示例中你可以使用 <literal>java.lang</literal> 和 
-		<literal>java.util</literal> 包中的类,
-		还有用户自定义的Java Bean来构建数据对象:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>使用 <literal>java.lang.String</literal> 来构建字符串。</para>
-          </listitem>
-
-          <listitem>
-            <para>使用 <literal>java.lang.Number</literal> 来派生数字类型。</para>
-          </listitem>
-
-          <listitem>
-            <para>使用 <literal>java.lang.Boolean</literal> 来构建布尔值。</para>
-          </listitem>
-
-          <listitem>
-            <para>使用 <literal>java.util.List</literal> 或Java数组来构建序列。</para>
-          </listitem>
-
-          <listitem>
-            <para>使用 <literal>java.util.Map</literal> 来构建哈希表。</para>
-          </listitem>
-
-          <listitem>
-            <para>使用自定义的bean类来构建哈希表,bean中的项和bean的属性对应。比如, 
-            <literal>product</literal> 的 <literal>price</literal> 属性
-			(<literal>getProperty()</literal>)可以通过 <literal>product.price</literal> 
-			获取。(bean的action也可以通过这种方式拿到;
-			要了解更多可以参看 <link linkend="pgui_misc_beanwrapper">这里</link>)</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>我们为 <link 
-		linkend="example.first">模板开发指南部分演示的第一个例子</link>
-		来构建数据模型。为了方便说明,这里再展示一次示例:</para>
-
-        <programlisting role="dataModel">(root)
-  |
-  +- user = "Big Joe"
-  |
-  +- latestProduct
-      |
-      +- url = "products/greenmouse.html"
-      |
-      +- name = "green mouse"</programlisting>
-
-        <para>下面是构建这个数据模型的Java代码片段:</para>
-
-        <programlisting role="unspecified">// Create the root hash
-Map&lt;String, Object&gt; root = new HashMap&lt;&gt;();
-// Put string ``user'' into the root
-root.put("user", "Big Joe");
-// Create the hash for ``latestProduct''
-Map&lt;String, Object&gt; latest = new HashMap&lt;&gt;();
-// and put it into the root
-root.put("latestProduct", latest);
-// put ``url'' and ``name'' into latest
-latest.put("url", "products/greenmouse.html");
-latest.put("name", "green mouse");</programlisting>
-
-        <para>在真实应用系统中,通常会使用应用程序指定的类来代替 <literal>Map</literal>,
-		它会有JavaBean规范规定的
-		<literal>get<replaceable>Xxx</replaceable></literal>/<literal>is<replaceable>Xxx</replaceable></literal>
-		方法。比如有一个和下面类似的类:</para>
-
-        <programlisting role="unspecified">public class Product {
-
-    private String url;
-    private String name;
-    ...
-    
-    // As per the JavaBeans spec., this defines the "url" bean property
-    public String getUrl() {
-        return url;
-    }
-    
-    // As per the JavaBean spec., this defines the "name" bean property
-    public String getName() {
-        return name;
-    }
-    
-    ...
-    
-}</programlisting>
-
-        <para>将它的实例放入数据模型中,就像下面这样:</para>
-
-        <programlisting role="unspecified">Product latestProducts = getLatestProductFromDatabaseOrSomething();
-root.put("latestProduct", latestProduct);</programlisting>
-
-        <para>如果<literal>latestProduct</literal> 是 <literal>Map</literal>类型,
-		模板就可以是相同的,比如 <literal>${latestProduct.name}</literal> 
-		在两种情况下都好用。</para>
-
-        <para>根root本身也无需是 <literal>Map</literal>,只要是有
-		<literal>getUser()</literal> 和 <literal>getLastestProduct()</literal>
-		方法的对象即可。</para>
-
-        <note>
-          <para>如果配置设置项 <literal>object_wrapper</literal> 的值是用于所有真实步骤,
-		  这里描述的行为才好用。任何由 <literal>ObjectWrapper</literal> 包装成的哈希表
-		  可以用作根root,也可以在模板中和点、 <literal>[]</literal> 操作符使用。
-		  如果不是包装成哈希表的对象不能作为根root,也不能像那样在模板中使用。</para>
-        </note>
-      </section>
-
-      <section xml:id="pgui_quickstart_gettemplate">
-        <title>获取模板</title>
-
-        <indexterm>
-          <primary>template</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <para>模板代表了 <literal>freemarker.template.Template</literal> 
-		实例。典型的做法是从 <literal>Configuration</literal> 实例中获取一个
-		<literal>Template</literal> 实例。无论什么时候你需要一个模板实例,
-		都可以使用它的 <literal>getTemplate</literal> 方法来获取。在 <link 
-		linkend="pgui_quickstart_createconfiguration">之前</link> 设置的目录中的
-		<literal>test.ftl</literal> 文件中存储 <link 
-		linkend="example.first">示例模板</link>,那么就可以这样来做:</para>
-
-        <programlisting role="unspecified">Template temp = cfg.getTemplate("test.ftl");</programlisting>
-
-        <para>当调用这个方法的时候,将会创建一个 <literal>test.ftl</literal> 
-		的 <literal>Template</literal> 实例,通过读取 
-		<literal><replaceable>/where/you/store/templates/</replaceable>test.ftl</literal> 
-		文件,之后解析(编译)它。<literal>Template</literal> 实例以解析后的形式存储模板,
-		而不是以源文件的文本形式。</para>
-
-        <para><literal>Configuration</literal> 缓存 <literal>Template</literal> 
-		实例,当再次获得 <literal>test.ftl</literal> 的时候,它可能再读取和解析模板文件了,
-		而只是返回第一次的 <literal>Template</literal> 实例。</para>
-      </section>
-
-      <section xml:id="pgui_quickstart_merge">
-        <title>合并模板和数据模型</title>
-
-        <indexterm>
-          <primary>output</primary>
-
-          <secondary>generate with Java</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>merging</primary>
-        </indexterm>
-
-        <para>我们已经知道,数据模型+模板=输出,我们有了一个数据模型
-		(<literal>root</literal>) 和一个模板 (<literal>temp</literal>),
-		为了得到输出就需要合并它们。这是由模板的 <literal>process</literal> 
-		方法完成的。它用数据模型root和 <literal>Writer</literal> 
-		对象作为参数,然后向 <literal>Writer</literal> 对象写入产生的内容。
-		为简单起见,这里我们只做标准的输出:</para>
-
-        <programlisting role="unspecified">Writer out = new OutputStreamWriter(System.out);
-temp.process(root, out);</programlisting>
-
-        <para>这会向你的终端输出你在模板开发指南部分的 <link 
-		linkend="example.first">第一个示例</link> 中看到的内容。</para>
-
-        <para>Java I/O 相关注意事项:基于 <literal>out</literal> 对象,必须保证 
-		<literal>out.close()</literal> 最后被调用。当 <literal>out</literal> 
-		对象被打开并将模板的输出写入文件时,这是很电影的做法。其它时候,
-		比如典型的Web应用程序,那就  <emphasis>不能</emphasis> 关闭 
-		<literal>out</literal> 对象。FreeMarker 会在模板执行成功后
-		(也可以在 <literal>Configuration</literal> 中禁用) 
-		调用 <literal>out.flush()</literal>,所以不必为此担心。</para>
-
-        <para>请注意,一旦获得了 <literal>Template</literal> 实例,
-		就能将它和不同的数据模型进行不限次数
-		(<literal>Template</literal>实例是无状态的)的合并。此外,
-		当 <literal>Template</literal> 实例创建之后 
-		<literal>test.ftl</literal> 文件才能访问,而不是在调用处理方法时。</para>
-      </section>
-
-      <section xml:id="pgui_quickstart_all">
-        <title>将代码放在一起</title>
-
-        <para>这是一个由之前的代码片段组合在一起的源程序文件。
-		千万不要忘了将 <literal>freemarker.jar</literal> 
-		放到 <literal>CLASSPATH</literal> 中。</para>
-
-        <programlisting role="unspecified">import freemarker.template.*;
-import java.util.*;
-import java.io.*;
-
-public class Test {
-
-    public static void main(String[] args) throws Exception {
-        
-        /* ------------------------------------------------------------------------ */    
-        /* You should do this ONLY ONCE in the whole application life-cycle:        */    
-    
-        /* Create and adjust the configuration singleton */
-        Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
-        cfg.setDirectoryForTemplateLoading(new File("<replaceable>/where/you/store/templates</replaceable>"));
-        cfg.setDefaultEncoding("UTF-8");
-        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW);
-
-        /* ------------------------------------------------------------------------ */    
-        /* You usually do these for MULTIPLE TIMES in the application life-cycle:   */    
-
-        /* Create a data-model */
-        Map root = new HashMap();
-        root.put("user", "Big Joe");
-        Map latest = new HashMap();
-        root.put("latestProduct", latest);
-        latest.put("url", "products/greenmouse.html");
-        latest.put("name", "green mouse");
-
-        /* Get the template (uses cache internally) */
-        Template temp = cfg.getTemplate("test.ftl");
-
-        /* Merge data-model with template */
-        Writer out = new OutputStreamWriter(System.out);
-        temp.process(root, out);
-        // Note: Depending on what `out` is, you may need to call `out.close()`.
-        // This is usually the case for file output, but not for servlet output.
-    }
-}</programlisting>
-
-        <note>
-          <para>为了简单起见,这里压制了异常(在方法签名中声明了异常,译者注),
-		  而在正式运行的产品中不要这样做。</para>
-        </note>
-      </section>
-    </chapter>
-
-    <chapter xml:id="pgui_datamodel">
-      <title>数据模型</title>
-
-      <para>这只是一个介绍性的说明,可以查看 <olink 
-	  targetdoc="api">FreeMarker Java API文档</olink> 获取更多信息。</para>
-
-      <section xml:id="pgui_datamodel_basics">
-        <title>基本内容</title>
-
-        <indexterm>
-          <primary>object wrapper</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>wrapper</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>data-model</primary>
-
-          <secondary>assembling with Java, without object wrapper</secondary>
-        </indexterm>
-
-        <para>在 <link linkend="pgui_quickstart">入门</link> 章节中,
-		我们已经知道如何使用基本的Java类(<literal>Map</literal>, 
-		<literal>String</literal>,等)来构建数据模型了。在内部,模板中可用的变量都是实现了 
-		<literal>freemarker.template.TemplateModel</literal> 接口的Java对象。
-		但在数据模型中,可以使用基本的Java集合类作为变量,因为这些变量会在内部被替换为适当的
-		<literal>TemplateModel</literal> 类型。这种功能特性被称作是
-		<emphasis role="term">对象包装</emphasis>。对象包装功能可以透明地把 
-		<emphasis>任何</emphasis> 类型的对象转换为实现了 <literal>TemplateModel</literal> 
-		接口类型的实例。这就使得下面的转换成为可能,如在模板中把 
-		<literal>java.sql.ResultSet</literal> 转换为序列变量,
-		把 <literal>javax.servlet.ServletRequest</literal> 对象转换成包含请求属性的哈希表变量,
-		甚至可以遍历XML文档作为FTL变量(<link linkend="xgui">参考这里</link>)。包装(转换)这些对象,
-		需要使用合适的,也就是所谓的 <literal>对象包装器</literal> 实现(可能是自定义的实现);
-		这将在<link linkend="pgui_datamodel_objectWrapper">后面</link>讨论。
-		现在的要点是想从模板访问任何对象,它们早晚都要转换为实现了 <literal>TemplateModel</literal> 
-		接口的对象。那么首先你应该熟悉来写 <literal>TemplateModel</literal> 接口的实现类。</para>
-
-        <para>有一个粗略的 <literal>freemarker.template.TemplateModel</literal> 
-		子接口对应每种基本变量类型(<literal>TemplateHashModel</literal> 对应哈希表,
-        <literal>TemplateSequenceModel</literal> 对应序列,
-        <literal>TemplateNumberModel</literal> 对应数字等等)。比如,想为模板使用
-        <literal>java.sql.ResultSet</literal> 变量作为一个序列,那么就需要编写一个
-        <literal>TemplateSequenceModel</literal> 的实现类,这个类要能够读取
-        <literal>java.sql.ResultSet</literal> 中的内容。我们常这么说,使用 
-		<literal>TemplateModel</literal> 的实现类 <emphasis>包装</emphasis> 了
-        <literal>java.sql.ResultSet</literal>,基本上只是封装
-		<literal>java.sql.ResultSet</literal> 来提供使用普通的
-        <literal>TemplateSequenceModel</literal> 接口访问它。请注意一个类可以实现多个
-        <literal>TemplateModel</literal> 接口;这就是为什么FTL变量可以有多种类型
-		(参看 <xref linkend="dgui_datamodel_basics"/>)</para>
-
-        <para>请注意,这些接口的一个细小的实现是和 
-		<literal>freemarker.template</literal> 包一起提供的。
-		例如,将一个 <literal>String</literal> 转换成FTL的字符串变量,
-		可以使用 <literal>SimpleScalar</literal>,将 <literal>java.util.Map</literal> 
-		转换成FTL的哈希表变量,可以使用 <literal>SimpleHash</literal> 等等。</para>
-
-        <para>如果想尝试自己的 <literal>TemplateModel</literal> 实现,
-		一个简单的方式是创建它的实例,然后将这个实例放入数据模型中
-		(也就是把它 <literal>放到</literal> 哈希表的根root上)。
-		对象包装器将会给模板提供它的原状,因为它已经实现了 
-		<literal>TemplateModel</literal> 接口,所以没有转换(包装)的需要。
-		(这个技巧当你不想用对象包装器来包装(转换)某些对象时仍然有用。)</para>
-      </section>
-
-      <section xml:id="pgui_datamodel_scalar">
-        <title>标量</title>
-
-        <indexterm>
-          <primary>scalar</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>string</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>number</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>boolean</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>date</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>time</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <para>有4种类型的标量:</para>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para>布尔值</para>
-          </listitem>
-
-          <listitem>
-            <para>数字</para>
-          </listitem>
-
-          <listitem>
-            <para>字符串</para>
-          </listitem>
-
-          <listitem>
-            <para>日期类型(子类型: 日期(没有时间部分),时间或者日期-时间)</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>每一种标量类型都是
-        <literal>Template<replaceable>Type</replaceable>Model</literal>
-        接口的实现,这里的 <literal><replaceable>Type</replaceable></literal> 
-		就是类型的名称。这些接口只定义了一个方法:
-        <literal><replaceable>type</replaceable>
-        getAs<replaceable>Type</replaceable>();</literal>。
-		它返回变量的Java类型(<literal>boolean</literal>,
-        <literal>Number</literal>, <literal>String</literal> 和
-        <literal>Date</literal> 各自代表的值)。</para>
-
-        <note>
-          <para>由于历史遗留的原因,字符串标量的接口是
-		  <literal>TemplateScalarModel</literal>,而不是
-          <literal>TemplateStringModel</literal>。
-		  (因为早期的 FreeMarker 字符串就是标量。)</para>
-        </note>
-
-        <para>这些接口的一个细小的实现和 
-		<literal>Simple<replaceable>Type</replaceable></literal> 
-		类名在 <literal>freemarker.template</literal> 包中是可用的。
-		但是却没有 <literal>SimpleBooleanModel</literal> 类型;为了代表布尔值,
-		可以使用 <literal>TemplateBooleanModel.TRUE</literal> 和 
-		<literal>TemplateBooleanModel.FALSE</literal> 来单独使用。</para>
-
-        <note>
-          <para>由于历史遗留的原因,字符串标量的实现类是 
-		  <literal>SimpleScalar</literal>,而不是 
-		  <literal>SimpleString</literal>。</para>
-        </note>
-
-        <para>在FTL中标量是一成不变的。当在模板中设置变量的值时,
-		使用其他的实例来替换 
-		<literal>Template<replaceable>Type</replaceable>Model</literal> 实例时,
-		是不用改变原来实例中存储的值的。</para>
-
-        <section>
-          <title><quote>日期</quote> 类型的难点</title>
-
-          <indexterm>
-            <primary>date</primary>
-
-            <secondary>Java API related difficulties</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>time</primary>
-
-            <secondary>Java API related difficulties</secondary>
-          </indexterm>
-
-          <para>对于日期类型来说,有一些难题,因为Java API通常不区别 
-		  <literal>java.util.Date</literal> 只存储日期部分(April 4, 2003),
-		  时间部分(10:19:18 PM),或两者都存(April 4, 2003 10:19:18 PM)。
-		  为了用本文正确显示值(或者进行其它确定的操作),FreeMarker必须知道 
-		  <literal>java.util.Date</literal> 的哪个部分存储了有意义上的信息,
-		  哪部分没有被使用(通常是标记为0的)。不幸的是,
-		  通常该信息只是当值从数据库中取得时可用,
-		  因为大多数数据库有独立的日期,时间和日期-时间(又叫做时间戳)类型,
-		  <literal>java.sql</literal> 有3个对应的 
-		  <literal>java.util.Date</literal> 子类和它们相匹配。</para>
-
-          <para><literal>TemplateDateModel</literal> 接口有两个方法:分别是
-		  <literal>java.util.Date getAsDate()</literal> 和 <literal>int getDateType()</literal>。
-		  该接口典型的实现是存储一个 <literal>java.util.Date</literal> 对象,
-		  加上一个整数来辨别子类型。这个整数的值也必须是 <literal>TemplateDateModel</literal> 
-		  接口中的常量之一:<literal>DATE</literal>, <literal>TIME</literal>,
-          <literal>DATETIME</literal> 和 <literal>UNKNOWN</literal>。</para>
-
-          <para>关于 <literal>UNKNOWN</literal>: <literal>java.lang</literal>
-          和 <literal>java.util</literal> 下的类通常被自动转换成 
-		  <literal>TemplateModel</literal> 的实现类,就是所谓的 
-		  <literal>对象包装器ObjectWrapper</literal>(请参考之前的对象包装介绍)。
-		  如果对象包装器要包装 <literal>java.util.Date</literal> 类,
-		  它不是 <literal>java.sql</literal> 日期类的实例,那就不能决定子类型是什么,
-		  所以使用 <literal>UNKNOWN</literal>。之后,如果模板需要使用这个变量,
-		  而且操作也需要子类型,那就会停止执行并抛出错误。为了避免这种情况的发生,
-		  对于那些可能有问题的变量,模板开发人员必须明确地指定子类型,使用内建函数 <link 
-		  linkend="ref_builtin_date_datetype"><literal>date</literal>,
-		  <literal>time</literal> 或 <literal>datetime</literal></link>
-		  (比如 <literal>lastUpdated?datetime</literal>)。请注意,
-		  如果和格式化参数一起使用内建函数 <literal>string</literal>,
-		  比如foo?string("MM/dd/yyyy"),那么 FreeMarker 就不必知道子类型了。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_datamodel_parent">
-        <title>容器</title>
-
-        <indexterm>
-          <primary>containers</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <para>容器包括哈希表,序列和集合三种类型。</para>
-
-        <section>
-          <title>哈希表</title>
-
-          <indexterm>
-            <primary>hash</primary>
-
-            <secondary>Java side</secondary>
-          </indexterm>
-
-          <para>哈希表是实现了 <literal>TemplateHashModel</literal> 
-		  接口的Java对象。<literal>TemplateHashModel</literal> 有两个方法:
-          <literal>TemplateModel get(String key)</literal>,这个方法根据给定的名称返回子变量,
-		  <literal>boolean isEmpty()</literal>,这个方法表明哈希表是否含有子变量。
-		  <literal>get</literal> 方法当在给定的名称没有找到子变量时返回null。</para>
-
-          <para><literal>TemplateHashModelEx</literal> 接口扩展了
-          <literal>TemplateHashModel</literal>。它增加了更多的方法,使得可以使用内建函数 
-		  <link linkend="ref_builtin_values">values</link> 和 
-		  <link linkend="ref_builtin_keys">keys</link> 来枚举哈希表中的子变量。</para>
-
-          <para>经常使用的实现类是 <literal>SimpleHash</literal>,该类实现了 
-          <literal>TemplateHashModelEx</literal> 接口。从内部来说,它使用一个 
-          <literal>java.util.Hash</literal> 类型的对象存储子变量。
-          <literal>SimpleHash</literal> 类的方法可以添加和移除子变量。
-		  这些方法应该用来在变量被创建之后直接初始化。</para>
-
-          <para>在FTL中,容器是一成不变的。那就是说你不能添加,替换和移除容器中的子变量。</para>
-        </section>
-
-        <section>
-          <title>序列</title>
-
-          <indexterm>
-            <primary>sequence</primary>
-
-            <secondary>Java side</secondary>
-          </indexterm>
-
-          <para>序列是实现了 <literal>TemplateSequenceModel</literal> 
-		  接口的Java对象。它包含两个方法:<literal>TemplateModel get(int index)</literal> 
-		  和 <literal>int size()</literal>。</para>
-
-          <para>经常使用的实现类是 <literal>SimpleSequence</literal>。该类内部使用一个 
-          <literal>java.util.List</literal> 类型的对象存储它的子变量。
-          <literal>SimpleSequence</literal> 有添加子元素的方法。
-		  在序列创建之后应该使用这些方法来填充序列。</para>
-        </section>
-
-        <section>
-          <title>集合</title>
-
-          <indexterm>
-            <primary>collection</primary>
-
-            <secondary>Java side</secondary>
-          </indexterm>
-
-          <para>集合是实现了 <literal>TemplateCollectionModel</literal> 
-		  接口的Java对象。这个接口定义了一个方法:
-		  <literal>TemplateModelIterator iterator()</literal>。
-          <literal>TemplateModelIterator</literal> 接口和 
-		  <literal>java.util.Iterator</literal> 相似,但是它返回 
-		  <literal>TemplateModels</literal> 而不是 <literal>Object</literal>,
-		  而且它能抛出 <literal>TemplateModelException</literal> 异常。</para>
-
-          <para>通常使用的实现类是 <literal>SimpleCollection</literal>。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_datamodel_method">
-        <title>方法</title>
-
-        <indexterm>
-          <primary>method</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <para>方法变量在存于实现了 <literal>TemplateMethodModel</literal> 
-		接口的模板中。这个接口包含一个方法:
-		<literal>TemplateModel exec(java.util.List arguments)</literal>。
-		当使用 <link linkend="dgui_template_exp_methodcall">方法调用表达式</link>
-		调用方法时,<literal>exec</literal> 方法将会被调用。
-		形参将会包含FTL方法调用形参的值。<literal>exec</literal> 
-		方法的返回值给出了FTL方法调用表达式的返回值。</para>
-
-        <para><literal>TemplateMethodModelEx</literal> 接口扩展了 
-		<literal>TemplateMethodModel</literal> 接口。它没有添加任何新方法。
-		事实上这个对象实现这个 <emphasis>标记</emphasis> 接口是给FTL引擎暗示,
-		形式参数应该直接以 <literal>TemplateModel</literal> 的形式放进 
-		<literal>java.util.List</literal>。否则将会以 
-		<literal>String</literal> 形式放入list。</para>
-
-        <para>出于这些很明显的原因,这些接口没有默认的实现。</para>
-
-        <para>例如:下面这个方法,返回第一个字符串在第二个字符串第一次出现时的索引位置,
-		如果第二个字符串中不包含第一个字符串,则返回-1:</para>
-
-        <programlisting role="unspecified">public class IndexOfMethod implements TemplateMethodModel {
-    
-    public TemplateModel exec(List args) throws TemplateModelException {
-        if (args.size() != 2) {
-            throw new TemplateModelException("Wrong arguments");
-        }
-        return new SimpleNumber(
-            ((String) args.get(1)).indexOf((String) args.get(0)));
-    }
-}</programlisting>
-
-        <para>如果将一个实例放入根数据模型中,像这样:</para>
-
-        <programlisting role="unspecified">root.put("indexOf", new IndexOfMethod());</programlisting>
-
-        <para>那么就可以在模板中调用:</para>
-
-        <programlisting role="template">&lt;#assign x = "something"&gt;
-${indexOf("met", x)}
-${indexOf("foo", x)}</programlisting>
-
-        <para>将会输出:</para>
-
-        <programlisting role="output">2
--1</programlisting>
-
-        <para>如果需要访问FTL运行时环境(读/写变量,获取本地化信息等),则可以使用 
-        <literal>Environment.getCurrentEnvironment()</literal> 来获取。</para>
-      </section>
-
-      <section xml:id="pgui_datamodel_directive">
-        <title>指令</title>
-
-        <indexterm>
-          <primary>directives</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <para>Java程序员可以使用 <literal>TemplateDirectiveModel</literal> 
-		接口在Java代码中实现自定义指令。详情可以参加API文档。</para>
-
-        <note>
-          <para><literal>TemplateDirectiveModel</literal> 在 FreeMarker 2.3.11 版本时才加入,
-          来代替快被废弃的 <literal>TemplateTransformModel</literal>。</para>
-        </note>
-
-        <section>
-          <title>示例 1</title>
-
-          <para>我们要实现一个指令,
-		  这个指令可以将在它开始标签和结束标签之内的字符都转换为大写形式。
-		  就像这个模板:</para>
-
-          <programlisting role="template">foo
-<emphasis>&lt;@upper&gt;</emphasis>
-  bar
-  &lt;#-- All kind of FTL is allowed here --&gt;
-  &lt;#list ["red", "green", "blue"] as color&gt;
-    ${color}
-  &lt;/#list&gt;
-  baaz
-<emphasis>&lt;/@upper&gt;</emphasis>
-wombat</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">foo
-  BAR
-    RED
-    GREEN
-    BLUE
-  BAAZ
-wombat</programlisting>
-
-          <para>下面是指令类的源代码:</para>
-
-          <programlisting role="unspecified">package com.example;
-import java.io.IOException;
-import java.io.Writer;
-import java.util.Map;
-
-import freemarker.core.Environment;
-import freemarker.template.TemplateDirectiveBody;
-import freemarker.template.TemplateDirectiveModel;
-import freemarker.template.TemplateException;
-import freemarker.template.TemplateModel;
-import freemarker.template.TemplateModelException;
-
-/**
- *  FreeMarker user-defined directive that progressively transforms
- *  the output of its nested content to upper-case.
- *  
- *  
- *  &lt;p&gt;&lt;b&gt;Directive info&lt;/b&gt;&lt;/p&gt;
- * 
- *  &lt;p&gt;Directive parameters: None
- *  &lt;p&gt;Loop variables: None
- *  &lt;p&gt;Directive nested content: Yes
- */
-public class UpperDirective implements TemplateDirectiveModel {
-    
-    public void execute(Environment env,
-            Map params, TemplateModel[] loopVars,
-            TemplateDirectiveBody body)
-            throws TemplateException, IOException {
-        // Check if no parameters were given:
-        if (!params.isEmpty()) {
-            throw new TemplateModelException(
-                    "This directive doesn't allow parameters.");
-        }
-        if (loopVars.length != 0) {
-                throw new TemplateModelException(
-                    "This directive doesn't allow loop variables.");
-        }
-        
-        // If there is non-empty nested content:
-        if (body != null) {
-            // Executes the nested body. Same as &lt;#nested&gt; in FTL, except
-            // that we use our own writer instead of the current output writer.
-            body.render(new UpperCaseFilterWriter(env.getOut()));
-        } else {
-            throw new RuntimeException("missing body");
-        }
-    }
-    
-    /**
-     * A {@link Writer} that transforms the character stream to upper case
-     * and forwards it to another {@link Writer}.
-     */ 
-    private static class UpperCaseFilterWriter extends Writer {
-       
-        private final Writer out;
-           
-        UpperCaseFilterWriter (Writer out) {
-            this.out = out;
-        }
-
-        public void write(char[] cbuf, int off, int len)
-                throws IOException {
-            char[] transformedCbuf = new char[len];
-            for (int i = 0; i &lt; len; i++) {
-                transformedCbuf[i] = Character.toUpperCase(cbuf[i + off]);
-            }
-            out.write(transformedCbuf);
-        }
-
-        public void flush() throws IOException {
-            out.flush();
-        }
-
-        public void close() throws IOException {
-            out.close();
-        }
-    }
-
-}</programlisting>
-
-          <para>现在我们需要创建这个类的实例,
-		  然后让这个指令在模板中可以通过名称"upper"来访问
-		  (或者是其它我们想用的名字)。一个可行的方案是把这个指令放到数据模型中:</para>
-
-          <programlisting role="unspecified">root.put("upper", new com.example.UpperDirective());</programlisting>
-
-          <para>但更好的做法是将常用的指令作为 <link 
-		  linkend="pgui_config_sharedvariables">共享变量</link> 
-		  放到 <literal>Configuration</literal> 中。</para>
-
-          <para>当然也可以使用 <link 
-		  linkend="ref_builtin_new">内建函数<literal>new</literal></link>
-		  将指令放到一个FTL库(宏的集合,就像在模板中,
-		  使用 <literal>include</literal> 或 <literal>import</literal> )中:</para>
-
-          <programlisting role="template">&lt;#-- Maybe you have directives that you have implemented in FTL --&gt;
-&lt;#macro something&gt;
-  ...
-&lt;/#macro&gt;
-
-&lt;#-- Now you can't use &lt;#macro upper&gt;, but instead you can: --&gt;
-&lt;#assign upper = "com.example.UpperDirective"?new()&gt;
-</programlisting>
-        </section>
-
-        <section>
-          <title>示例 2</title>
-
-          <para>我们来创建一个指令,这个指令可以一次又一次地执行其中的嵌套内容,
-		  这个次数由指定的数字来确定(就像 <literal>list</literal> 指令),
-		  可以使用<literal>&lt;hr&gt;</literal>将输出的重复内容分开。
-		  这个指令我们命名为"repeat"。示例模板如下:</para>
-
-          <programlisting role="template">&lt;#assign x = 1&gt;
-
-<emphasis>&lt;@repeat count=4&gt;</emphasis>
-  Test ${x}
-  &lt;#assign x++&gt;
-<emphasis>&lt;/@repeat&gt;</emphasis>
-
-<emphasis>&lt;@repeat count=3 hr=true&gt;</emphasis>
-  Test
-<emphasis>&lt;/@repeat&gt;</emphasis>
-
-<emphasis>&lt;@repeat count=3; cnt&gt;</emphasis>
-  ${cnt}. Test
-<emphasis>&lt;/@repeat&gt;</emphasis></programlisting>
-
-          <para>输出为:</para>
-
-          <programlisting role="output">  Test 1
-  Test 2
-  Test 3
-  Test 4
-
-  Test
-&lt;hr&gt;  Test
-&lt;hr&gt;  Test
-
-  1. Test
-  2. Test
-  3. Test
- </programlisting>
-
-          <para>指令的实现类为:</para>
-
-          <programlisting role="unspecified">package com.example;
-import java.io.IOException;
-import java.io.Writer;
-import java.util.Iterator;
-import java.util.Map;
-
-import freemarker.core.Environment;
-import freemarker.template.SimpleNumber;
-import freemarker.template.TemplateBooleanModel;
-import freemarker.template.TemplateDirectiveBody;
-import freemarker.template.TemplateDirectiveModel;
-import freemarker.template.TemplateException;
-import freemarker.template.TemplateModel;
-import freemarker.template.TemplateModelException;
-import freemarker.template.TemplateNumberModel;
-
-/**
- * FreeMarker user-defined directive for repeating a section of a template,
- * optionally with separating the output of the repetations with
- * &lt;tt&gt;&amp;lt;hr&gt;&lt;/tt&gt;-s.
- *
- * 
- * &lt;p&gt;&lt;b&gt;Directive info&lt;/b&gt;&lt;/p&gt;
- * 
- * &lt;p&gt;Parameters:
- * &lt;ul&gt;
- *   &lt;li&gt;&lt;code&gt;count&lt;/code&gt;: The number of repetations. Required!
- *       Must be a non-negative number. If it is not a whole number then it will
- *       be rounded &lt;em&gt;down&lt;/em&gt;.
- *   &lt;li&gt;&lt;code&gt;hr&lt;/code&gt;: Tells if a HTML "hr" element could be printed between
- *       repetations. Boolean. Optional, defaults to &lt;code&gt;false&lt;/code&gt;. 
- * &lt;/ul&gt;
- *
- * &lt;p&gt;Loop variables: One, optional. It gives the number of the current
- *    repetation, starting from 1.
- * 
- * &lt;p&gt;Nested content: Yes
- */
-public class RepeatDirective implements TemplateDirectiveModel {
-    
-    private static final String PARAM_NAME_COUNT = "count";
-    private static final String PARAM_NAME_HR = "hr";
-    
-    public void execute(Environment env,
-            Map params, TemplateModel[] loopVars,
-            TemplateDirectiveBody body)
-            throws TemplateException, IOException {
-        
-        // ---------------------------------------------------------------------
-        // Processing the parameters:
-        
-        int countParam = 0;
-        boolean countParamSet = false;
-        boolean hrParam = false;
-        
-        Iterator paramIter = params.entrySet().iterator();
-        while (paramIter.hasNext()) {
-            Map.Entry ent = (Map.Entry) paramIter.next();
-            
-            String paramName = (String) ent.getKey();
-            TemplateModel paramValue = (TemplateModel) ent.getValue();
-            
-            if (paramName.equals(PARAM_NAME_COUNT)) {
-                if (!(paramValue instanceof TemplateNumberModel)) {
-                    throw new TemplateModelException(
-                            "The \"" + PARAM_NAME_HR + "\" parameter "
-                            + "must be a number.");
-                }
-                countParam = ((TemplateNumberModel) paramValue)
-                        .getAsNumber().intValue();
-                countParamSet = true;
-                if (countParam &lt; 0) {
-                    throw new TemplateModelException(
-                            "The \"" + PARAM_NAME_HR + "\" parameter "
-                            + "can't be negative.");
-                }
-            } else if (paramName.equals(PARAM_NAME_HR)) {
-                if (!(paramValue instanceof TemplateBooleanModel)) {
-                    throw new TemplateModelException(
-                            "The \"" + PARAM_NAME_HR + "\" parameter "
-                            + "must be a boolean.");
-                }
-                hrParam = ((TemplateBooleanModel) paramValue)
-                        .getAsBoolean();
-            } else {
-                throw new TemplateModelException(
-                        "Unsupported parameter: " + paramName);
-            }
-        }
-        if (!countParamSet) {
-                throw new TemplateModelException(
-                        "The required \"" + PARAM_NAME_COUNT + "\" paramter"
-                        + "is missing.");
-        }
-        
-        if (loopVars.length &gt; 1) {
-                throw new TemplateModelException(
-                        "At most one loop variable is allowed.");
-        }
-        
-        // Yeah, it was long and boring...
-        
-        // ---------------------------------------------------------------------
-        // Do the actual directive execution:
-        
-        Writer out = env.getOut();
-        if (body != null) {
-            for (int i = 0; i &lt; countParam; i++) {
-                // Prints a &lt;hr&gt; between all repetations if the "hr" parameter
-                // was true:
-                if (hrParam &amp;&amp; i != 0) {
-                    out.write("&lt;hr&gt;");
-                }
-                
-                // Set the loop variable, if there is one:
-                if (loopVars.length &gt; 0) {
-                    loopVars[0] = new SimpleNumber(i + 1);
-                }
-                
-                // Executes the nested body (same as &lt;#nested&gt; in FTL). In this
-                // case we don't provide a special writer as the parameter:
-                body.render(env.getOut());
-            }
-        }
-    }
-
-}</programlisting>
-        </section>
-
-        <section>
-          <title>注意</title>
-
-          <para><literal>TemplateDirectiveModel</literal> 
-		  对象通常不应该是有状态的,这一点非常重要。
-		  一个经常犯的错误是存储指令的状态然后在对象的属性中调用执行。
-		  想一下相同指令的嵌入调用,或者指令对象被用作共享变量,
-		  并通过多线程同时访问。</para>
-
-          <para>不幸的是, <literal>TemplateDirectiveModel</literal> 
-		  不支持传递参数的位置(而不是参数名称)。从 FreeMarker 2.4 版本开始,它将被修正。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_datamodel_node">
-        <title>结点变量</title>
-
-        <indexterm>
-          <primary>node</primary>
-
-          <secondary>Java side</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>tree nodes</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>trees</primary>
-        </indexterm>
-
-        <para>结点变量体现了树形结构中的结点。结点变量的引入是为了帮助用户 <link 
-		linkend="xgui">在数据模型中处理XML文档</link>,
-		但是它们也可以用于构建树状模型。如需要有关从模板语言角度考虑的结点信息,
-		那么可以 <link linkend="dgui_datamodel_node">阅读之前章节</link>。</para>
-
-        <para>结点变量有下列属性,它们都由 
-		<literal>TemplateNodeModel</literal> 接口的方法提供:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>基本属性:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para><literal>TemplateSequenceModel getChildNodes()</literal>:
-				一个结点的子结点序列(除非这个结点是叶子结点,这时方法返回一个空序列或者是null)。
-				子结点本身应该也是结点变量。</para>
-              </listitem>
-
-              <listitem>
-                <para><literal>TemplateNodeModel getParentNode()</literal>:
-				一个结点只有一个父结点(除非这个结点是结点树的根结点,
-				这时方法返回<literal>null</literal>)。</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-
-          <listitem>
-            <para>可选属性。如果一个属性在具体的使用中没有意义,
-			那对应的方法应该返回<literal>null</literal>:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para><literal>String getNodeName()</literal>:
-				结点名称也是宏的名称,当使用 <link 
-				linkend="ref.directive.recurse"><literal>recurse</literal></link> 和 <link 
-				linkend="ref.directive.visit"><literal>visit</literal></link>指令时,
-				它用来控制结点。因此,如果想通过结点使用这些指令,
-				那么结点的名称是 <emphasis>必须的</emphasis>。</para>
-              </listitem>
-
-              <listitem>
-                <para><literal>String getNodeType()</literal>:在XML中:
-				<literal>"element"</literal>,<literal>"text"</literal>,
-				<literal>"comment"</literal>等。如果这些信息可用,
-				就是通过 <literal>recurse</literal> 和 <literal>visit</literal> 
-				指令来查找结点的默认处理宏。而且,它对其他有具体用途的应用程序也是有用的。</para>
-              </listitem>
-
-              <listitem>
-                <para><literal>String getNamespaceURI()</literal>:
-				这个结点所属的命名空间(和用于库的FTL命名空间无关)。例如,在XML中,
-				这就是元素和属性所属XML命名空间的URI。这个信息如果可用,就是通过 
-				<literal>recurse</literal> 和 <literal>visit</literal> 
-				指令来查找存储控制宏的FTL命名空间。</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-        </itemizedlist>
-
-        <para>在FTL里,结点属性的直接使用可以通过 <link 
-		linkend="ref_builtins_node">内建函数 node</link>完成,
-		还有 <literal>visit</literal> 和 <literal>recurse</literal> 宏。</para>
-
-        <para>在很多用例中,实现了 <literal>TemplateNodeModel</literal> 
-		接口和其它接口的变量,因为结点变量属性仅仅提供基本的结点间导航的方法。
-		需要具体的例子,请参考 <link linkend="xgui">FreeMarker如何处理XML</link> 部分。</para>
-      </section>
-
-      <section xml:id="pgui_datamodel_objectWrapper">
-        <title>对象包装</title>
-
-        <indexterm>
-          <primary>object wrapper</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>wrapper</primary>
-        </indexterm>
-
-        <para>对象包装器是实现了 <literal>freemarker.template.ObjectWrapper</literal> 
-		接口的类。它的目标是实现Java对象(应用程序中特定类等,比如 <literal>String</literal>,
-		<literal>Map</literal>,<literal>List</literal> 实例)和FTL类型系统之间的映射。换句话说,
-		它指定了模板如何在数据模型(包含从模板中调用的Java方法的返回值)中发现Java对象。
-		对象包装器作为插件放入 <literal>Configuration</literal> 中,可以使用
-		<literal>object_wrapper</literal> 属性设置
-		(或者使用<literal>Configuration.setObjectWrapper</literal>)。</para>
-
-        <para>从技术角度来说,FTL类型系统由之前介绍过的 <literal>TemplateModel</literal> 子接口
-		(<literal>TemplateScalarModel</literal>,<literal>TemplateHashMode</literal>,
-        <literal>TemplateSequenceModel</literal>等)来表示。要映射Java对象到FTL类型系统中,
-		对象包装器的 <literal>TemplateModel wrap(java.lang.Object obj)</literal> 方法会被调用。</para>
-
-        <para>有时FreeMarker需要撤回映射,此时 <literal>对象包装器ObjectWrapper</literal> 
-		的 <literal>Object unwrap(TemplateModel)</literal> 方法就被调用了
-		(或其他的变化,请参考API文档来获取详细内容)。最后的操作是在
-        <literal>ObjectWrapperAndUnwrapper</literal> 中,它是
-        <literal>ObjectWrapper</literal> 的子接口。很多实际的包装器会实现 
-        <literal>ObjectWrapperAndUnwrapper</literal> 接口。</para>
-
-        <para>我们来看一下包装Java对象并包含其他对象
-		(比如 <literal>Map</literal>,<literal>List</literal>,数组,
-		或者有JavaBean属性的对象)是如何进行的。可以这么说,对象包装器将 
-		<literal>Object[]</literal> 数组包装成 <literal>TemplateSquenceModel</literal> 
-		接口的一些实现。当FreeMarker需要FTL序列中项的时候,它会调用 
-        <literal>TemplateSquenceModel.get(int index)</literal> 方法。该方法的返回值是 
-        <literal>TemplateModel</literal>,也就是说,<literal>TemplateSquenceModel</literal> 
-		实现不仅仅可以从给定的数组序列获取 <literal>对象</literal>,
-		也可以负责在返回它之前包装该值。为了解决这个问题,典型的 
-		<literal>TemplateSquenceModel</literal> 实现将会存储它创建的
-        <literal>ObjectWrapper</literal>,之后再调用该 <literal>ObjectWrapper</literal> 
-		来包装包含的值。相同的逻辑代表了 <literal>TemplateHashModel</literal> 或其他的
-        <literal>TemplateModel</literal>,它是其它 <literal>TemplateModel</literal> 的容器。
-		因此,通常不论值的层次结构有多深,所有值都会被同一个 <literal>ObjectWrapper</literal> 
-		包装。(要创建 <literal>TemplateModel</literal> 的实现类,请遵循这个原则,可以使用 
-		<literal>freemarker.template.WrappingTemplateModel</literal> 作为基类。)</para>
-
-        <para>数据模型本身(root变量)是 <literal>TemplateHashModel</literal>。
-		在 <literal>Template.process</literal> 中指定的root对象将会被在 
-		<literal>object_wrapper</literal> 配置中设置的对象包装器所包装,并产生一个
-        <literal>TemplateHashModel</literal>。从此,被包含值的包装遵循之前描述的逻辑
-		(比如,容器负责包装它的子实例)。</para>
-
-        <para>行为良好的对象包装器都会绕过已经实现 <literal>TemplateModel</literal> 
-		接口的对象。如果将已经实现 <literal>TemplateModel</literal> 的对象放到数据模型中
-		(或者从模板中调用的Java方法返回这个对象),那么就可以避免实际的对象包装。
-		当特别是通过模板访问创建的值时,通常会这么做。因此,要避免更多上面对象包装的性能问题,
-		但也可以精确控制模板可以看到的内容(不是基于当前对象包装器的映射策略)。
-		常见的应用程序使用该手法是使用 <literal>freemarker.template.SimpleHash</literal> 
-		作为数据模型的根root(而不是<literal>Map</literal>),当使用 <literal>SimpleHash</literal>
-		的 <literal>put</literal> 方法来填充(这点很重要,它不会复制已经填充并存在的
-		<literal>Map</literal>)。这会加快顶层数据模型变量的访问速度。</para>
-
-        <section xml:id="pgui_datamodel_defaultObjectWrapper">
-          <title>默认对象包装器</title>
-
-          <indexterm>
-            <primary>object wrapper</primary>
-
-            <secondary>default</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>DefaultObjectWrapper</primary>
-          </indexterm>
-
-          <para><literal>object_wrapper</literal> <literal>Configuration</literal> 
-		  的默认设置是 <literal>freemarker.template.DefaultObjectWrapper</literal> 
-		  实例。除非有特别的需求,那么建议使用这个对象包装器,或者是自定义的
-          <literal>DefaultObjectWrapper</literal> 的子类。</para>
-
-          <para>它会识别大部分基本的Java类型,比如 <literal>String</literal>,
-		  <literal>Number</literal>,<literal>Boolean</literal>,
-		  <literal>Date</literal>,<literal>List</literal> (通常还有全部的 
-		  <literal>java.util.Collection</literal> 类型),
-		  数组,<literal>Map</literal>等。并把它们自然地包装成匹配 
-		  <literal>TemplateModel</literal> 接口的对象。它也会使用
-		  <literal>freemarker.ext.dom.NodeModel</literal> 来包装W3C DOM结点,
-		  所以可以很方便地处理XML, <link linkend="xgui">在XML章节会有描述</link>)。
-		  对于Jython对象,会代理到 <literal>freemarker.ext.jython.JythonWrapper</literal> 上。
-		  而对于其它所有对象,则会调用 <literal>BeansWrapper.wrap</literal>(超类的方法),
-		  暴露出对象的JavaBean属性作为哈希表项
-		  (比如FTL中的 <literal>myObj.foo</literal> 会在后面调用 <literal>getFoo()</literal>),
-		  也会暴露出对象(比如FTL中的 <literal>myObj.bar(1, 2)</literal> 就会调用方法)
-		  的公有方法(JavaBean action)。(关于对象包装器的更多信息,请参阅
-		  <link linkend="pgui_misc_beanwrapper">该章节</link>。)</para>
-
-          <para>关于 <literal>DefaultObjectWrapper</literal> 更多值得注意的细节:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para>不用经常使用它的构造方法,而是使用 
-			  <literal>DefaultObjectWrapperBuilder</literal> 来创建它。
-			  这就允许 FreeMarker 使用单例。</para>
-            </listitem>
-
-            <listitem xml:id="topic.defaultObjectWrapperIcI">
-              <para><literal>DefaultObjectWrapper</literal> 有
-              <literal>incompatibleImprovements</literal> 属性,
-			  这在 2.3.22 或更高版本中是极力推荐的(参看该效果的 <link
-              xlink:href="https://freemarker.apache.org/docs/api/freemarker/template/DefaultObjectWrapper.html#DefaultObjectWrapper-freemarker.template.Version-">API文档</link>)。如何来设置:</para>
-
-              <itemizedlist>
-                <listitem>
-                  <para>如果已经在 2.3.22 或更高版本的 
-				  <emphasis><literal>Configuration</literal></emphasis> 
-				  中设置了 <literal>incompatible_improvements</literal> 选项,
-				  而没有设置 <literal>object_wrapper</literal> 选项(那么它就保留默认值),
-				  我们就什么都做不了了,因为它已经使用了同等 
-				  <literal>incompatibleImprovements</literal> 属性值的
-                  <literal>DefaultObjectWrapper</literal> 单例。</para>
-                </listitem>
-
-                <listitem xml:id="topic.setDefaultObjectWrapperIcIIndividually">
-                  <para>另外也可以在 <literal>Configuration</literal> 中独立设置
-                  <literal>incompatibleImprovements</literal>。基于如何创建/设置
-				  <literal>ObjectWrapper</literal>,可以通过这样完成
-                  (假设想要 <literal>incompatibleImprovements</literal> 2.3.22):</para>
-
-                  <itemizedlist>
-                    <listitem>
-                      <para>如果使用了构建器API:</para>
-
-                      <programlisting role="unspecified">... = new DefaultObjectWrapperBuilder(Configuration.VERSION_2_3_22).build()</programlisting>
-                    </listitem>
-
-                    <listitem>
-                      <para>或者使用构造方法:</para>
-
-                      <programlisting role="unspecified">... = new DefaultObjectWrapper(Configuration.VERSION_2_3_22)</programlisting>
-                    </listitem>
-
-                    <listitem>
-                      <para>或者使用 <literal>object_wrapper</literal> 属性
-                      (<literal>*.properties</literal> 文件或
-                      <literal>java.util.Properties</literal> 对象):</para>
-
-                      <programlisting role="unspecified">object_wrapper=DefaultObjectWrapper(2.3.21)</programlisting>
-                    </listitem>
-
-                    <listitem>
-                      <para>或者通过 <literal>FreemarkerServlet</literal> 配置
-					  <literal>object_wrapper</literal> 和在 
-					  <literal>web.xml</literal> 中的 
-					  <literal>init-param</literal> 属性来配置:</para>
-
-                      <programlisting role="unspecified">&lt;init-param&gt;
-    &lt;param-name&gt;object_wrapper&lt;/param-name&gt;
-    &lt;param-value&gt;DefaultObjectWrapper(2.3.21)&lt;/param-value&gt;
-&lt;/init-param&gt;</programlisting>
-                    </listitem>
-                  </itemizedlist>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para>在新的或测试覆盖良好的项目中,也建议设置
-              <literal>forceLegacyNonListCollections</literal> 
-			  属性为 <literal>false</literal>。
-			  如果使用 <literal>.properties</literal> 或
-              <literal>FreemarkerServlet</literal> 初始化参数,就会像
-              <literal>DefaultObjectWrapper(2.3.22, forceLegacyNonListCollections=false)</literal>,
-			  同时,使用Java API可以在 <literal>DefaultObjectWrapperBuilder</literal> 对象调用
-			  <literal>build()</literal> 之前调用
-              <literal>setForceLegacyNonListCollections(false)</literal>。</para>
-            </listitem>
-
-            <listitem>
-              <para>自定义
-              <literal>DefaultObjectWrapper</literal> 的最常用方法是覆盖
-              <literal>handleUnknownType</literal> 方法。</para>
-            </listitem>
-          </itemizedlist>
-        </section>
-
-        <section xml:id="pgui_datamodel_customObjectWrappingExample">
-          <title>自定义对象包装示例</title>
-
-          <indexterm>
-            <primary>object wrapper</primary>
-
-            <secondary>custom</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>custom object wrapper</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>DefaultObjectWrapper</primary>
-
-            <secondary>extending</secondary>
-          </indexterm>
-
-          <para>我们假定有一个应用程序特定的类,像下面这样:</para>
-
-          <programlisting role="unspecified">package com.example.myapp;
-
-public class Tupple&lt;E1, E2&gt; {
-    public Tupple(E1 e1, E2 e2) { ... }
-    public E1 getE1() { ... }
-    public E2 getE2() { ... }
-}</programlisting>
-
-          <para>若想让模板将它视作长度为2的序列,那么就可以这么来调用
-		  <literal>someTupple[1]</literal>,
-          <literal>&lt;#list someTupple
-          <replaceable>...</replaceable>&gt;</literal>, 或者
-          <literal>someTupple?size</literal>。需要创建一个
-          <literal>TemplateSequenceModel</literal> 实现来适配
-          <literal>Tupple</literal> 到
-          <literal>TempateSequenceMoldel</literal> 接口:</para>
-
-          <programlisting role="unspecified">package com.example.myapp.freemarker;
-
-...
-
-public class TuppleAdapter extends WrappingTemplateModel implements TemplateSequenceModel,
-        AdapterTemplateModel {
-    
-    private final Tupple&lt;?, ?&gt; tupple;
-    
-    public TuppleAdapter(Tupple&lt;?, ?&gt; tupple, ObjectWrapper ow) {
-        super(ow);  // coming from WrappingTemplateModel
-        this.tupple = tupple;
-    }
-
-    @Override  // coming from TemplateSequenceModel
-    public int size() throws TemplateModelException {
-        return 2;
-    }
-    
-    @Override  // coming from TemplateSequenceModel
-    public TemplateModel get(int index) throws TemplateModelException {
-        switch (index) {
-        case 0: return wrap(tupple.getE1());
-        case 1: return wrap(tupple.getE2());
-        default: return null;
-        }
-    }
-
-    @Override  // coming from AdapterTemplateModel
-    public Object getAdaptedObject(Class hint) {
-        return tupple;
-    }
-    
-}</programlisting>
-
-          <para>关于类和接口:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para><literal>TemplateSequenceModel</literal>:
-			  这就是为什么模板将它视为序列</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>WrappingTemplateModel</literal>:
-			  只是一个方便使用的类,用于 <literal>TemplateModel</literal> 
-			  对象进行自身包装。通常仅对包含其它对象的对象需要。
-              参考上面的 <literal>wrap(<replaceable>...</replaceable>)</literal> 调用。</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>AdapterTemplateModel</literal>:
-			  表明模板模型适配一个已经存在的对象到 
-              <literal>TemplateModel</literal> 接口,
-			  那么去掉包装就会给出原有对象。</para>
-            </listitem>
-          </itemizedlist>
-
-          <para>最后,我们告诉 FreeMarker 用 <literal>TuppleAdapter</literal> 
-		  (或者,可以在将它们传递到FreeMarker之前手动包装它们)
-		  包装 <literal>Tupple</literal>。那样的话,首先创建一个自定义的对象包装器:</para>
-
-          <programlisting role="unspecified">package com.example.myapp.freemarker;
-
-...
-
-public class MyAppObjectWrapper extends DefaultObjectWrapper {
-
-    public MyAppObjectWrapper(Version incompatibleImprovements) {
-        super(incompatibleImprovements);
-    }
-    
-    @Override
-    protected TemplateModel handleUnknownType(final Object obj) throws TemplateModelException {
-        if (obj instanceof Tupple) {
-            return new TuppleAdapter((Tupple&lt;?, ?&gt;) obj, this);
-        }
-        
-        return super.handleUnknownType(obj);
-    }
-    
-}</programlisting>
-
-          <para>那么当配置 FreeMarker (<link 
-		  linkend="pgui_config">关于配置,参考这里...</link>)
-		  将我们的对象包装器插在:</para>
-
-          <programlisting role="unspecified">// Where you initialize the cfg *singleton* (happens just once in the application life-cycle):
-cfg = new Configuration(Configuration.VERSION_2_3_22);
-...
-cfg.setObjectWrapper(new MyAppObjectWrapper(cfg.getIncompatibleImprovements()));</programlisting>
-
-          <para>或者使用 <literal>java.util.Properties</literal> 来代替配置 
-		  FreeMarker (也就是 <literal>.properties</literal> 文件):</para>
-
-          <programlisting role="unspecified">object_wrapper=com.example.myapp.freemarker.MyAppObjectWrapper(2.3.22)</programlisting>
-        </section>
-      </section>
-    </chapter>
-
-    <chapter xml:id="pgui_config">
-      <title>配置(Configuration)</title>
-
-      <indexterm>
-        <primary>Configuration</primary>
-      </indexterm>
-
-      <para>这里仅仅是一个概览,若要了解更多请阅读 
-	  <olink targetdoc="api">FreeMarker Java API 文档</olink>。</para>
-
-      <section xml:id="pgui_config_basics">
-        <title>基本内容</title>
-
-        <para>首先,确保你已经阅读了 <link 
-		linkend="pgui_quickstart_createconfiguration">入门</link> 章节。</para>
-
-        <para>配置(configuration)就是
-        <literal>freemarker.template.Configuration</literal> 对象,
-		它存储了常用(全局,应用程序级)的设置,定义了想要在所有模板中可用的变量(称为共享变量)。
-		而且,它会处理 <literal>Template</literal> 实例的新建和缓存。</para>
-
-        <para>应用程序典型的用法是使用一个独立的共享
-        <literal>Configuration</literal> 实例。更精确来说,
-		典型的做法是每一个独立开发的组件(比如项目,模块等)都有一个
-        <literal>Configuration</literal> 实例,它在内部使用FreeMarker,
-		每一个都创建它自己的实例。</para>
-
-        <para>运行中的模板会受配置设置的影响,每个 <literal>Template</literal> 
-		实例通过对应 <literal>Template</literal> 构造方法参数,都有和它相关联的
-		<literal>Configuration</literal> 实例。通常可以使用 
-		<literal>Configuration.getTemplate</literal> 
-		(而不是直接调用 <literal>Template</literal> 的构造方法)来获得 
-		<literal>Template</literal> 实例,此时,关联的 <literal>Configuration</literal> 
-		实例就是调用 <literal>getTemplate</literal> 方法的。</para>
-      </section>
-
-      <section xml:id="pgui_config_sharedvariables">
-        <title>共享变量</title>
-
-        <indexterm>
-          <primary>shared variable</primary>
-        </indexterm>
-
-        <para><emphasis role="term">Shared variables</emphasis>
-		(共享变量)是为所有模板定义的变量。可以使用 
-		<literal>setSharedVariable</literal> 方法向配置中添加共享变量:</para>
-
-        <programlisting role="unspecified">Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
-<replaceable>..</replaceable>.
-cfg.setSharedVariable("warp", new WarpDirective());
-cfg.setSharedVariable("company", "Foo Inc.");</programlisting>
-
-        <para>在所有使用这个配置的模板中,名为 <literal>wrap</literal> 
-		的用户自定义指令和一个名为 <literal>company</literal> 
-		的字符串将会在数据模型的根root上可见,
-		那就不用在根哈希表上一次又一次的添加它们。在传递给 
-		<literal>Template.process</literal> 的
-		根root对象里的变量将会隐藏同名的共享变量。</para>
-
-        <warning>
-          <para>如果配置对象在多线程环境中使用,不要使用 
-		  <literal>TemplateModel</literal> 实现类来作为共享变量,
-		  因为它是不是<link linkend="gloss.threadSafe">线程安全</link>的!
-		  这也是基于Servlet应用程序的典型情形。</para>
-        </warning>
-
-        <para>出于向后兼容的特性,共享变量的集合初始化时
-		(就是对于新的 <literal>Configuration</literal> 实例来说)不能为空。
-		它包含下列用户自定义指令(用户自定义指令使用时需要用 
-		<literal>@</literal> 来代替<literal>#</literal>):</para>
-
-        <informaltable border="1">
-          <thead>
-            <tr>
-              <th>名称</th>
-
-              <th>类</th>
-            </tr>
-          </thead>
-
-          <tbody>
-            <tr>
-              <td><literal>capture_output</literal></td>
-
-              <td><literal>freemarker.template.utility.CaptureOutput</literal></td>
-            </tr>
-
-            <tr>
-              <td><literal>compress</literal></td>
-
-              <td><literal>freemarker.template.utility.StandardCompress</literal></td>
-            </tr>
-
-            <tr>
-              <td><literal>html_escape</literal></td>
-
-              <td><literal>freemarker.template.utility.HtmlEscape</literal></td>
-            </tr>
-
-            <tr>
-              <td><literal>normalize_newlines</literal></td>
-
-              <td><literal>freemarker.template.utility.NormalizeNewlines</literal></td>
-            </tr>
-
-            <tr>
-              <td><literal>xml_escape</literal></td>
-
-              <td><literal>freemarker.template.utility.XmlEscape</literal></td>
-            </tr>
-          </tbody>
-        </informaltable>
-      </section>
-
-      <section xml:id="pgui_config_settings">
-        <title>配置设置</title>
-
-        <indexterm>
-          <primary>setting</primary>
-        </indexterm>
-
-        <para><emphasis role="term">Settings</emphasis>(配置设置)
-		是影响FreeMarker行为的已被命名的值。配置设置有很多,
-		例如:<literal>locale</literal>,<literal>number_format</literal>,
-		<literal>default_encoding</literal>,
-        <literal>template_exception_handler</literal>。可以参考 <link
-        xlink:href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-">
-		<literal>Configuration.setSetting(...)</literal>的Java API 文档</link>
-		来查看配置设置的完整列表。</para>
-
-        <para>配置设置存储在 <literal>Configuration</literal> 实例中,可以在 
-        <literal>Template</literal> 实例中被覆盖。比如,在配置中给 
-		<literal>locale</literal> 设置为 <literal>"en_US"</literal>,
-		那么使用该配置的所有模板中的 
-		<literal>locale</literal> 都使用 <literal>"en_US"</literal>,
-		除非在模板中locale被明确地设置成其它不同的值(参见
-		<link linkend="ref_directive_include_localized">localization</link>)。
-		因此,在 <literal>Configuration</literal> 中的值充当默认值,
-		这些值在每个模板中也可以被覆盖。在 <literal>Configuration</literal> 
-		或 <literal>Template</literal> 实例中的值也可以在单独调用 
-		<literal>Template.process</literal> 方法后被覆盖。
-        对于每个调用了 <literal>freemarker.core.Environment</literal> 
-		对象的值在内部创建时就持有模板执行的运行时环境,也包括了那个级别被覆盖了的设置信息。
-		在模板执行时,那里存储的值也可以被改变,所以模板本身也可以设置配置信息,
-		比如在输出中途来变换 <literal>locale</literal> 设置。</para>
-
-        <para>配置信息可以被想象成3层(<literal>Configuration</literal>,
-		<literal>Template</literal>,<literal>Environment</literal>),
-		最高层包含特定的值,它为设置信息提供最有效的值。
-		比如(设置信息A到F仅仅是为这个示例而构想的):</para>
-
-        <informaltable border="1">
-          <col align="left"/>
-
-          <col align="center" span="6"/>
-
-          <thead>
-            <tr>
-              <th/>
-
-              <th>Setting A</th>
-
-              <th>Setting B</th>
-
-              <th>Setting C</th>
-
-              <th>Setting D</th>
-
-              <th>Setting E</th>
-
-              <th>Setting F</th>
-            </tr>
-          </thead>
-
-          <tbody>
-            <tr>
-              <td>Layer 3: <literal>Environment</literal></td>
-
-              <td>1</td>
-
-              <td>-</td>
-
-              <td>-</td>
-
-              <td>1</td>
-
-              <td>-</td>
-
-              <td>-</td>
-            </tr>
-
-            <tr>
-              <td>Layer 2: <literal>Template</literal></td>
-
-              <td>2</td>
-
-              <td>2</td>
-
-              <td>-</td>
-
-              <td>-</td>
-
-              <td>2</td>
-
-              <td>-</td>
-            </tr>
-
-            <tr>
-              <td>Layer 1: <literal>Configuration</literal></td>
-
-              <td>3</td>
-
-              <td>3</td>
-
-              <td>3</td>
-
-              <td>3</td>
-
-              <td>-</td>
-
-              <td>-</td>
-            </tr>
-          </tbody>
-        </informaltable>
-
-        <para>配置信息的有效值为:A=1,B=2,C=3,D=1,E=2。
-		而F的设置则是 <literal>null</literal>,或者在你获取它的时候将抛出异常。</para>
-
-        <para>我们看看如何准确设置配置信息:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para><literal>Configuration</literal> 层:
-			原则上设置配置信息时使用 <literal>Configuration</literal> 
-			对象的setter方法,例如:</para>
-
-            <programlisting role="unspecified">Configuration myCfg = new Configuration(Configuration.VERSION_2_3_23);
-myCfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
-myCfg.setDefaultEncoding("UTF-8");</programlisting>
-
-            <para>在真正使用 <literal>Configuration</literal> 对象
-			(通常在初始化应用程序时)之前来配置它,后面必须将其视为只读的对象。</para>
-
-            <para>在实践中,比如很多Web应用框架中,就应该使用这种框架特定的配置方式来进行配置,
-			比如使用成对的 <literal>String</literal> 来配置(像在 
-			<literal>.properties</literal> 属性配置文件中那样)。
-			在这种情况下,框架的作者大多数使用 <literal>Configuration</literal> 
-			对象的 <literal>setSetting(String name, String value) </literal>方法。
-			这可以参考<link
-            xlink:href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-"><literal>setSetting</literal>的API文档</link>
-			部分来获取可用的设置名和参数的格式的信息。
-			而在Spring框架中,我们可以这样进行:</para>
-
-            <programlisting role="unspecified">&lt;bean id="freemarkerConfig"
-    class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"&gt;
-  &lt;property name="freemarkerSettings"&gt;
-    &lt;props&gt;
-      &lt;prop key="incompatible_improvements"&gt;2.3.23&lt;/prop&gt;
-      &lt;prop key="template_exception_handler"&gt;rethrow&lt;/prop&gt;
-      &lt;prop key="default_encoding"&gt;UTF-8&lt;/prop&gt;
-    &lt;/props&gt;
-  &lt;/property&gt;
-&lt;/bean&gt;</programlisting>
-
-            <para>请注意,这种形式的配置( <literal>String</literal> 键-值对)
-			和直接使用 <literal>Configuration</literal> 的API相比,
-			很不幸地被限制了。</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>Template</literal> 层:对于被请求的本地化信息,模板的
-            <literal>locale</literal> 设置由 
-			<literal>Configuration.getTemplate(...)</literal> 来设置。
-			否则,就不能在这里进行设置,除非想控制 <literal>Template</literal> 
-			对象来代替 <literal>freemarker.cache.TemplateCache</literal>,这样的话,
-			应该在 <literal>Template</literal> 对象第一次被使用前就设置配置信息,
-			然后就将 <literal>Template</literal> 对象视为是只读的。</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>Environment </literal>层:这里有两种配置方法:</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>使用Java API:使用 <literal>Environment</literal> 
-				对象的setter方法。当然想要在模板执行之前来做,然后当调用 
-				<literal>myTemplate.process(...)</literal> 时会遇到问题,
-				因为在内部创建 <literal>Environment</literal> 对象后立即就执行模板了,
-				导致没有机会来进行设置。这个问题的解决可以用下面两个步骤进行:</para>
-
-                <programlisting role="unspecified">Environment env = myTemplate.createProcessingEnvironment(root, out);
-env.setLocale(java.util.Locale.ITALY);
-env.setNumberFormat("0.####");
-env.process();  // process the template</programlisting>
-              </listitem>
-
-              <listitem>
-                <para>在模板中(通常这被认为是不好的做法)直接使用 <link 
-				linkend="ref.directive.setting"><literal>setting</literal>
-                指令</link>,例如:</para>
-
-                <programlisting role="template">&lt;#setting locale="it_IT"&gt;
-&lt;#setting number_format="0.####"&gt;</programlisting>
-              </listitem>
-            </itemizedlist>
-
-            <para>在这层,当什么时候改变配置信息,是没有限制的。</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>要知道 FreeMarker 支持什么样的配置信息还有它们的意义,
-		可以先看看FreeMarker Java API文档中的下面这部分内容:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>在三层中 <literal>freemarker.core.Configurable</literal> 
-			的setter方法来配置。</para>
-          </listitem>
-
-          <listitem>
-            <para>只在 <literal>Configuration</literal> 层可用的
-			<literal>freemarker.template.Configuration</literal> 
-			的setter方法来配置。</para>
-          </listitem>
-
-          <listitem>
-            <para>在三层中可用 <literal>String</literal> 键-值对书写的 
-			<literal>freemarker.core.Configurable.setSetting(String,String)</literal>
-			配置。</para>
-          </listitem>
-
-          <listitem>
-            <para>只在 <literal>Configuration</literal> 层中可用 
-			<literal>String</literal> 键-值对书写的 
-			<literal>freemarker.template.Configuration.setSetting(String, String)</literal>
-			配置。</para>
-          </listitem>
-        </itemizedlist>
-      </section>
-
-      <section xml:id="pgui_config_templateloading">
-        <title>模板加载</title>
-
-        <indexterm>
-          <primary>loading templates</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>template loading</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>storing templates</primary>
-        </indexterm>
-
-        <section>
-          <title>模板加载器</title>
-
-          <indexterm>
-            <primary>template loaders</primary>
-          </indexterm>
-
-          <para>模板加载器是加载基于抽象模板路径下,比如 
-		  <literal>"index.ftl"</literal>  或 
-		  <literal>"products/catalog.ftl"</literal> 的原生文本数据对象。
-		  这由具体的模板加载器对象来确定它们取得请求数据时使用了什么样的数据来源
-		  (文件夹中的文件,数据等等)。当调用 <literal>cfg.getTemplate</literal> 
-		  (这里的 <literal>cfg</literal> 就是 <literal>Configuration</literal> 实例)时,
-		  FreeMarker询问模板加载器是否已经为 <literal>cfg</literal> 
-		  建立返回给定模板路径的文本,之后 FreeMarker 解析文本生成模板。</para>
-
-          <section>
-            <title>内建模板加载器</title>
-
-            <para>在 <literal>Configuration</literal> 
-			中可以使用下面的方法来方便建立三种模板加载。
-			(每种方法都会在其内部新建一个模板加载器对象,然后创建 
-			<literal>Configuration</literal> 实例来使用它。)</para>
-
-            <programlisting role="unspecified">void setDirectoryForTemplateLoading(File dir);</programlisting>
-
-            <para>或</para>
-
-            <programlisting role="unspecified">void setClassForTemplateLoading(Class cl, String prefix);</programlisting>
-
-            <para>或</para>
-
-            <programlisting role="unspecified">void setServletContextForTemplateLoading(Object servletContext, String path);</programlisting>
-
-            <para>上述的第一种方法在磁盘的文件系统上设置了一个明确的目录,
-			它确定了从哪里加载模板。不要说可能,<literal>File</literal> 
-			参数肯定是一个存在的目录。否则,将会抛出异常。</para>
-
-            <para>第二种调用方法使用了一个 <literal>Class</literal> 
-			类型的参数和一个前缀。这是让你来指定什么时候通过相同的机制来加载模板,
-			不过是用Java的 <literal>ClassLoader</literal> 来加载类。
-			这就意味着传入的class参数会被 <literal>Class.getResource()</literal> 
-			用来调用方法来找到模板。参数 <literal>prefix</literal> 
-			是给模板的名称来加前缀的。在实际运行的环境中,
-			类加载机制是首选用来加载模板的方法,通常情况下,从类路径下加载文件的这种机制,
-			要比从文件系统的特定目录位置加载安全而且简单。在最终的应用程序中,
-			所有代码都使用 <literal>.jar</literal> 文件打包也是不错的,
-			这样用户就可以直接执行包含所有资源的 <literal>.jar</literal> 文件了。</para>
-
-            <para>第三种调用方式需要Web应用的上下文和一个基路径作为参数,
-			这个基路径是Web应用根路径(<literal>WEB-INF</literal>目录的上级目录)的相对路径。
-			那么加载器将会从Web应用目录开始加载模板。尽管加载方法对没有打包的 
-			<literal>.war</literal> 文件起作用,因为它使用了 
-			<literal>ServletContext.getResource()</literal> 方法来访问模板,
-			注意这里我们指的是“目录”。如果忽略了第二个参数(或使用了<literal>""</literal>),
-			那么就可以混合存储静态文件(<literal>.html</literal>,<literal>.jpg</literal>等)
-			和 <literal>.ftl</literal> 文件,只是 <literal>.ftl</literal> 文件可以被送到客户端执行。
-			当然必须在 <literal>WEB-INF/web.xml</literal> 中配置一个Servlet来处理URI格式为
-			<literal>*.ftl</literal> 的用户请求,否则客户端无法获取到模板,
-			因此你将会看到Web服务器给出的秘密提示内容。在站点中不能使用空路径,这是一个问题,
-			你应该在 <literal>WEB-INF</literal> 目录下的某个位置存储模板文件,
-			这样模板源文件就不会偶然地被执行到,这种机制对servlet应用程序来加载模板来说,
-			是非常好用的方式,而且模板可以自动更新而不需重启Web应用程序,
-			但是对于类加载机制,这样就行不通了。</para>
-          </section>
-
-          <section>
-            <title>从多个位置加载模板</title>
-
-            <para>如果需要从多个位置加载模板,那就不得不为每个位置都实例化模板加载器对象,
-			将它们包装到一个称为 <literal>MultiTemplateLoader</literal> 的特殊模板加载器,
-			最终将这个加载器传递给 <literal>Configuration</literal> 对象的
-			<literal>setTemplateLoader(TemplateLoader loader)</literal>方法。
-			下面给出一个使用类加载器从两个不同位置加载模板的示例:</para>
-
-            <programlisting role="unspecified">import freemarker.cache.*; // template loaders live in this package
-
-<replaceable>...</replaceable>
-
-FileTemplateLoader ftl1 = new FileTemplateLoader(new File("/tmp/templates"));
-FileTemplateLoader ftl2 = new FileTemplateLoader(new File("/usr/data/templates"));
-ClassTemplateLoader ctl = new ClassTemplateLoader(getClass(), "");
-TemplateLoader[] loaders = new TemplateLoader[] { ftl1, ftl2, ctl };
-MultiTemplateLoader mtl = new MultiTemplateLoader(loaders);
-
-cfg.setTemplateLoader(mtl);</programlisting>
-
-            <para>现在,FreeMarker将会尝试从 <literal>/tmp/templates</literal> 
-			目录加载模板,如果在这个目录下没有发现请求的模板,它就会继续尝试从 
-			<literal>/usr/data/templates</literal> 目录下加载,如果还是没有发现请求的模板,
-			那么它就会使用类加载器来加载模板。</para>
-          </section>
-
-          <section>
-            <title>从其他资源加载模板</title>
-
-            <para>如果内建的类加载器都不适合使用,那么就需要来编写自己的类加载器了,
-			这个类需要实现 <literal>freemarker.cache.TemplateLoader</literal> 接口,
-			然后将它传递给 <literal>Configuration</literal> 对象的 
-			<literal>setTemplateLoader(TemplateLoader loader)</literal>方法。
-			可以阅读API JavaDoc文档获取更多信息。</para>
-
-            <para>如果模板需要通过URL访问其他模板,那么就不需要实现 
-			<literal>TemplateLoader</literal> 接口了,可以选择子接口 
-			<literal>freemarker.cache.URLTemplateLoader</literal> 来替代,
-			只需实现 <literal>URL getURL(String templateName)</literal> 方法即可。</para>
-          </section>
-
-          <section>
-            <title>模板名称(模板路径)</title>
-
-            <indexterm>
-              <primary>path</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>template path</primary>
-            </indexterm>
-
-            <indexterm>
-              <primary>template name</primary>
-            </indexterm>
-
-            <para>解析模板的名称(也就是模板路径)是由模板解析器来决定的。
-			但是要和其它对路径的格式要求很严格的组件一起使用。通常来说,
-			强烈建议模板加载器使用URL风格的路径。
-			在URL路径(或在UN*X路径)中符号有其它含义时,那么路径中不要使用 
-			<literal>/</literal>(路径分隔符)字符,<literal>.</literal>
-			(同目录符号)和<literal>..</literal>(父目录符号)。字符 
-			<literal>*</literal>(星号)是被保留的,
-			它用于FreeMarker的 <quote>模板获取</quote> 特性。</para>
-
-            <para><literal>://</literal>(或者使用 
-			<literal>template_name_format</literal> 配置设置到
-            <literal>DEFAULT_2_4_0</literal>,<literal>:</literal> (冒号)
-            字符)是被保留用来指定体系部分的,和URI中的相似。比如 
-			<literal>someModule://foo/bar.ftl</literal> 使用 
-			<literal>someModule</literal>,或者假定 <literal>DEFAULT_2_4_0</literal> 
-			格式,<literal>classpath:foo/bar.ftl</literal> 使用
-			<literal>classpath</literal> 体系。解释体系部分完全由 
-			<literal>TemplateLoader</literal> 决定。
-			(FreeMarker核心仅仅知道体系的想法,否则它不能正常处理相对模板名称。)</para>
-
-            <para>FreeMarker通常在将路径传递到 <literal>TemplateLoader</literal> 
-			之前把它们正常化,所以路径中不会包含 <literal>/../</literal> 这样的内容,
-			路径会相对于虚构的模板根路径(也就是它们不会以 <literal>/</literal> 开头)。
-			其中也不会包含 <literal>*</literal>,因为模板获取发生在很早的阶段。
-			此外,将 <literal>template_name_format</literal> 设置为 
-			<literal>DEFAULT_2_4_0</literal>,多个连续的 <literal>/</literal> 
-			将会被处理成单独的 <literal>/</literal> 
-			(除非它们是 <literal>://</literal> 模式分隔符的一部分)。</para>
-
-            <para>请注意,不管主机运行的操作系统是什么,
-			FreeMarker 模板加载时经常使用斜线(而不是反斜线)。</para>
-          </section>
-        </section>
-
-        <section xml:id="pgui_config_templateloading_caching">
-          <title>模板缓存</title>
-
-          <indexterm>
-            <primary>caching</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>template caching</primary>
-          </indexterm>
-
-          <para>FreeMarker 是会缓存模板的(假设使用 <literal>Configuration</literal> 
-		  对象的方法来创建 <literal>Template</literal> 对象)。这就是说当调用 
-		  <literal>getTemplate</literal>方法时,FreeMarker不但返回了 
-		  <literal>Template</literal> 对象,而且还会将它存储在缓存中,
-		  当下一次再以相同(或相等)路径调用 <literal>getTemplate</literal> 方法时,
-		  那么它只返回缓存的 <literal>Template</literal> 实例,
-		  而不会再次加载和解析模板文件了。</para>
-
-          <para>如果更改了模板文件,当下次调用模板时,FreeMarker 将会自动重新载入和解析模板。
-		  然而,要检查模板文件是否改变内容了是需要时间的,有一个 
-		  <literal>Configuration</literal> 级别的设置被称作"更新延迟",它可以用来配置这个时间。
-		  这个时间就是从上次对某个模板检查更新后,FreeMarker再次检查模板所要间隔的时间。
-		  其默认值是5秒。如果想要看到模板立即更新的效果,那么就要把它设置为0。
-		  要注意某些模板加载器也许在模板更新时可能会有问题。
-		  例如,典型的例子就是在基于类加载器的模板加载器就不会注意到模板文件内容的改变。</para>
-
-          <para>当调用了 <literal>getTemplate</literal> 方法时,
-		  与此同时FreeMarker意识到这个模板文件已经被移除了,所以这个模板也会从缓存中移除。
-		  如果Java虚拟机认为会有内存溢出时,默认情况它会从缓存中移除任意模板。
-		  此外,你还可以使用 <literal>Configuration</literal> 对象的
-		  <literal>clearTemplateCache</literal> 方法手动清空缓存。</para>
-
-          <para>何时将一个被缓存了的模板清除的实际应用策略是由配置的属性
-		  <literal>cache_storage</literal> 来确定的,通过这个属性可以配置任何
-		  <literal>CacheStorage</literal> 的实现。对于大多数用户来说,
-		  使用 <literal>freemarker.cache.MruCacheStorage</literal> 就足够了。
-		  这个缓存存储实现了二级最近使用的缓存。在第一级缓存中,
-		  组件都被强烈引用到特定的最大数目(引用次数最多的组件不会被Java虚拟机抛弃,
-		  而引用次数很少的组件则相反)。当超过最大数量时,
-		  最近最少使用的组件将被送至二级缓存中,在那里它们被很少引用,
-		  直到达到另一个最大的数目。引用强度的大小可以由构造方法来指定。
-		  例如,设置强烈部分为20,轻微部分为250:</para>
-
-          <programlisting role="unspecified">cfg.setCacheStorage(new freemarker.cache.MruCacheStorage(20, 250))</programlisting>
-
-          <para>或者,使用 <literal>MruCacheStorage</literal> 缓存,
-		  它是默认的缓存存储实现:</para>
-
-          <programlisting role="unspecified">cfg.setSetting(Configuration.CACHE_STORAGE_KEY, "strong:20, soft:250");</programlisting>
-
-          <para>当创建了一个新的 <literal>Configuration</literal> 对象时,
-		  它使用一个 <literal>strongSizeLimit</literal> 值为0的 
-		  <literal>MruCacheStorage</literal> 缓存来初始化,
-		  <literal>softSizeLimit</literal> 的值是 <literal>Integer.MAX_VALUE</literal> 
-		  (也就是在实际中,是无限大的)。但是使用非0的 <literal>strongSizeLimit</literal> 
-		  对于高负载的服务器来说也许是一个更好的策略,对于少量引用的组件来说,
-		  如果资源消耗已经很高的话,Java虚拟机往往会引发更高的资源消耗,
-		  因为它不断从缓存中抛出经常使用的模板,这些模板还不得不再次加载和解析。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_config_errorhandling">
-        <title>错误控制</title>
-
-        <indexterm>
-          <primary>error handling</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>exception handling</primary>
-        </indexterm>
-
-        <section>
-          <title>可能的异常</title>
-
-          <para>关于 FreeMarker 发生的异常,可以分为如下几类:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para>当配置 FreeMarker 时发生异常:典型地情况,就是在应用程序初始化时,
-			  仅仅配置了一次 FreeMarker。在这个过程中,异常就会发生,
-			  从 FreeMarker 的API中,我们可以很清楚的看到这一点...</para>
-            </listitem>
-
-            <listitem>
-              <para>当加载和解析模板时发生异常:调用了 
-			  <literal>Configuration.getTemplate(<replaceable>...</replaceable>)</literal> 方法,
-			  FreeMarker就要把模板文件加载到内存中然后来解析它
-			  (除非模板已经在 <literal>Configuration</literal> 对象中被 <link 
-			  linkend="pgui_config_templateloading_caching">缓存</link> 了)。
-			  在这期间,有两种异常可能发生:</para>
-
-              <itemizedlist>
-                <listitem>
-                  <para>因模板文件没有找到而发生的 <literal>IOException</literal> 异常,
-				  或在读取文件时发生其他的I/O问题。比如没有读取文件的权限,或者是磁盘错误。
-				  这些错误的发出者是<link linkend="pgui_config_templateloading">
-				  <literal>TemplateLoader</literal> 对象</link>,可以将它作为插件设置到
-				  <literal>Configuration</literal>对象中。(为了正确起见:这里所说的”文件”,
-				  是简化形式。例如,模板也可以存储在关系型数据库的表中。这是 
-				  <literal>TemplateLoader</literal>所要做的事。)</para>
-                </listitem>
-
-                <listitem>
-                  <para>根据FTL语言的规则,模板文件发生语法错误时会导致 
-				  <literal>freemarker.core.ParseException</literal>异常。当获得 
-				  <literal>Template</literal>对象 
-				  (<literal>Configuration.getTemplate(<replaceable>...</replaceable>)</literal>)时,
-				  这种错误就会发生,而不是当执行 
-				  (<literal>Template.process(<replaceable>...</replaceable>)</literal>)模板的时候。
-				  这种异常是 <literal>IOException</literal> 的一个子类。</para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para>当执行(处理)模板时发生的异常,也就是当调用了 
-			  <literal>Template.process(<replaceable>...</replaceable>)</literal> 方法时会发生的两种异常:
-			  </para>
-
-              <itemizedlist>
-                <listitem>
-                  <para>当试图写入输出对象时发生错误而导致的 <literal>IOException</literal> 异常。</para>
-                </listitem>
-
-                <listitem>
-                  <para>当执行模板时发生的其它问题而导致的 
-				  <literal>freemarker.template.TemplateException</literal> 异常。
-				  比如,一个频繁发生的错误,就是当模板引用一个不存在的变量。
-				  默认情况下,当 <literal>TemplateException</literal> 异常发生时,
-				  FreeMarker会用普通文本格式在输出中打印出FTL的错误信息和堆栈跟踪信息,
-				  然后再次抛出 <literal>TemplateException</literal> 异常而中止模板的执行,
-				  就可以捕捉到 <literal>Template.process(<replaceable>...</replaceable>)</literal> 
-				  方法抛出的异常了。而这种行为是可以定制的。FreeMarker也会经常写 
-				  <literal>TemplateException</literal> 异常的 
-				  <link linkend="pgui_misc_logging">日志</link>。</para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-          </itemizedlist>
-        </section>
-
-        <section>
-          <title>根据TemplateException来自定义处理方式</title>
-
-          <para><literal>TemplateException</literal> 异常在模板处理期间的抛出是由 
-		  <literal>freemarker.template.TemplateExceptionHandler</literal> 
-		  对象控制的,这个对象可以使用 
-		  <literal>setTemplateExceptionHandler(<replaceable>...</replaceable>)</literal> 
-		  方法配置到 <literal>Configuration</literal> 对象中。
-		  <literal>TemplateExceptionHandler</literal> 对象只包含一个方法:</para>
-
-          <programlisting role="unspecified">void handleTemplateException(TemplateException te, Environment env, Writer out) 
-        throws TemplateException;</programlisting>
-
-          <para>无论 <literal>TemplateException</literal> 
-		  异常什么时候发生,这个方法都会被调用。
-		  异常处理是传递的 <literal>te</literal> 参数控制的,
-		  模板处理的运行时(Runtime,译者注)环境可以访问 <literal>env</literal> 变量,
-		  处理器可以使用 <literal>out</literal> 变量来打印输出信息。
-		  如果方法抛出异常(通常是重复抛出 <literal>te</literal>),那么模板的执行就会中止,
-		  而且 <literal>Template.process(<replaceable>...</replaceable>)</literal> 
-		  方法也会抛出同样的异常。如果 <literal>handleTemplateException</literal> 
-		  对象不抛出异常,那么模板将会继续执行,就好像什么也没有发生过一样,
-		  但是引发异常的语句将会被跳过(后面会详细说)。
-		  当然,控制器仍然可以在输出中打印错误提示信息。</para>
-
-          <para>任何一种情况下,当 <literal>TemplateExceptionHandler</literal> 被调用前,
-		  FreeMarker 将会记录异常<link linkend="pgui_misc_logging">日志</link>。</para>
-
-          <para>我们用实例来看一下,当错误控制器不抛出异常时,
-		  FreeMarker是如何跳过出错''语句''的。假设我们已经使用了如下模板异常控制器:</para>
-
-          <programlisting role="unspecified">class MyTemplateExceptionHandler implements TemplateExceptionHandler {
-    public void handleTemplateException(TemplateException te, Environment env, java.io.Writer out)
-            throws TemplateException {
-        try {
-            out.write("[ERROR: " + te.getMessage() + "]");
-        } catch (IOException e) {
-            throw new TemplateException("Failed to print error message. Cause: " + e, env);
-        }
-    }
-}
-
-<replaceable>...</replaceable>
-
-cfg.setTemplateExceptionHandler(new MyTemplateExceptionHandler());</programlisting>
-
-          <para>如果错误发生在非FTL标记(没有被包含在 
-		  <literal>&lt;#<replaceable>...</replaceable>&gt;</literal> 或 
-		  <literal>&lt;@<replaceable>...</replaceable>&gt;</literal>之间)的插值中,
-		  那么整个插值将会被跳过。那么下面这个模板
-		  (假设 <literal>badVar</literal> 在数据模型中不存在):</para>
-
-          <programlisting role="template">a${badVar}b</programlisting>
-
-          <para>如果我们使用了 <literal>MyTemplateExceptionHandler</literal>,就会打印:</para>
-
-          <programlisting role="output">a[ERROR: Expression badVar is undefined on line 1, column 4 in test.ftl.]b</programlisting>
-
-          <para>而下面这个模板也会打印相同信息(除了报错的列数位置会不同...):</para>
-
-          <programlisting role="template">a${"moo" + badVar}b</programlisting>
-
-          <para>因为像这样来写时,只要插值内发生任何错误,整个插值都会被跳过。</para>
-
-          <para>如果错误发生在指令调用中参数的计算时,或者是指令参数列表发生问题时,
-		  或在<literal>&lt;@<replaceable>exp</replaceable>
-		  <replaceable>...</replaceable>&gt;</literal>中计算 
-		  <literal><replaceable>exp</replaceable></literal>时发生错误,或者 
-		  <literal><replaceable>exp</replaceable></literal>不是用户自定义的指令,
-		  那么整个指令调用都会被跳过。例如:</para>
-
-          <programlisting role="template">a&lt;#if badVar&gt;Foo&lt;/#if&gt;b</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">a[ERROR: Expression badVar is undefined on line 1, column 7 in test.ftl.]b</programlisting>
-
-          <para>请注意,错误发生在 <literal>if</literal> 指令的开始标签
-		  (<literal>&lt;#if badVar&gt;</literal>)中,但是整个指令的调用都被跳过了。
-		  从逻辑上说,嵌套的内容(<literal>Foo</literal>)也被跳过了,
-		  因为嵌套的内容是受被包含的指令(<literal>if</literal>)控制(打印)的。</para>
-
-          <para>下面这个的输出也是相同的(除了报错的列数会不同...):</para>
-
-          <programlisting role="template">a&lt;#if "foo${badVar}" == "foobar"&gt;Foo&lt;/#if&gt;b</programlisting>
-
-          <para>因为,正如这样来写,在参数处理时发生任何一个错误,
-		  整个指令的调用都将会被跳过。</para>
-
-          <para>如果错误发生在已经开始执行的指令之后,那么指令调用将不会被跳过。
-		  也就是说,如果在嵌套的内容中发生任何错误:</para>
-
-          <programlisting role="template">a
-&lt;#if true&gt;
-  Foo
-  ${badVar}
-  Bar
-&lt;/#if&gt;
-c</programlisting>
-
-          <para>或者在一个宏定义体内:</para>
-
-          <programlisting role="template">a
-&lt;@test /&gt;
-b
-&lt;#macro test&gt;
-  Foo
-  ${badVar}
-  Bar
-&lt;/#macro&gt;</programlisting>
-
-          <para>那么输出将会是:</para>
-
-          <programlisting role="output">a
-  Foo
-  [ERROR: Expression badVar is undefined on line 4, column 5 in test.ftl.]
-  Bar
-c</programlisting>
-
-          <para>FreeMarker 本身带有这些预先编写的错误控制器:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para><literal>TemplateExceptionHandler.DEBUG_HANDLER</literal>:
-			  打印堆栈跟踪信息(包括FTL错误信息和FTL堆栈跟踪信息)和重新抛出的异常。
-			  这是默认的异常控制器(也就是说,在所有新的 <literal>Configuration</literal> 
-			  对象中,它是初始化好的)。</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>TemplateExceptionHandler.HTML_DEBUG_HANDLER</literal>:
-			  和 <literal>DEBUG_HANDLER</literal> 相同,但是它可以格式化堆栈跟踪信息,
-			  那么就可以在Web浏览器中来阅读错误信息。
-			  当你在制作HTML页面时,建议使用它而不是 <literal>DEBUG_HANDLER</literal>。</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>TemplateExceptionHandler.IGNORE_HANDLER</literal>:
-			  简单地压制所有异常(但是要记住,FreeMarker 仍然会写日志)。
-			  它对处理异常没有任何作用,也不会重新抛出异常。</para>
-            </listitem>
-
-            <listitem>
-              <para><literal>TemplateExceptionHandler.RETHROW_HANDLER</literal>:
-			  简单重新抛出所有异常而不会做其它的事情。
-			  这个控制器对Web应用程序(假设你在发生异常之后不想继续执行模板)来说非常好,
-			  因为它在生成的页面发生错误的情况下,给了你很多对Web应用程序的控制权
-			  (因为FreeMarker不向输出中打印任何关于该错误的信息)。
-			  要获得更多在Web应用程序中处理错误的信息,可以
-			  <link linkend="misc.faq.niceErrorPage">参见FAQ</link>。</para>
-            </listitem>
-          </itemizedlist>
-        </section>
-
-        <section>
-          <title>在模板中明确地处理错误</title>
-
-          <para>尽管它和 FreeMarker 的配置(本章的主题)无关,但是为了说明的完整性,
-		  在这里提及一下,你可以在模板中直接控制错误。
-		  通常这不是一个好习惯(尽量保持模板简单,技术含量不要太高),但有时仍然需要:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para>处理不存在/为空的变量: <xref
-              linkend="dgui_template_exp_missing"/></para>
-            </listitem>
-
-            <listitem>
-              <para>在发生障碍的"porlets"中留存下来,还可以扩展参考: <xref linkend="ref_directive_attempt"/></para>
-            </listitem>
-          </itemizedlist>
-        </section>
-      </section>
-
-      <section xml:id="pgui_config_incompatible_improvements">
-        <title>"不兼容改进"设置</title>
-
-        <indexterm>
-          <primary>incompatible improvements</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>incompatible_improvements</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>incompatibleImprovements</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>backward compatibility</primary>
-        </indexterm>
-
-        <section>
-          <title>它要做什么</title>
-
-          <para>该设置指定了 FreeMarker 的版本号,那么就不会100%向后兼容bug修复和改进 
-		  <emphasis>你想要启用</emphasis> 已经实现的内容。
-		  通常来说,默认把它留在2.3.0(最大向后兼容版本)是一个坏主意。</para>
-
-          <para>在新项目中,应该将它设置为实际使用的FreeMarker版本号。
-		  而在老项目中,那么最好也将它设置的高一些,最好检查一下哪些修改是激活状态(可以在 <link
-          xlink:href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-"><literal>Configuration(Version)</literal>
-          构造方法的API JavaDoc文档</link> 中找到它们),至少不仅仅是 
-		  <quote>不兼容改进</quote> 第三版本号(小版本)设置提高。通常来讲,
-		  只要为该设置增加最后的版本号,那么这些修改的风险就会小很多。</para>
-
-          <para>Bug修复和改进是完全向后兼容的,同样,它们也是重要的安全更新,
-		  不管 <quote>不兼容改进</quote> 如何设置都是启用的。</para>
-
-          <para>该设置的一个重要结果是应用程序可以检查声明的 FreeMarker 最小版本需求是否达到。
-		  比如你设置了2.3.22,但是应用程序却意外部署到了 FreeMarker 2.3.21,
-		  那么FreeMarker就会出问题,告诉你需要一个更高的版本。
-		  最后,请求的修复/改进不会作用于低版本。</para>
-        </section>
-
-        <section xml:id="pgui_config_incompatible_improvements_how_to_set">
-          <title>如何设置</title>
-
-          <para>这个不兼容改进的设置在 <literal>Configuration</literal> 级别。
-		  它可以在多种方式下设置(假设我们想将它设置为2.3.22):</para>
-
-          <itemizedlist>
-            <listitem>
-              <para>创建
-              <literal>freemarker.template.Configuration</literal> 对象,比如:</para>
-
-              <programlisting role="unspecified">... = new Configuration(Configuration.VERSION_2_3_22)</programlisting>
-            </listitem>
-
-            <listitem>
-              <para>或者,使用初始化设置来更改 <literal>Configuration</literal> 单例,比如:</para>
-
-              <programlisting role="unspecified">cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_22)</programlisting>
-            </listitem>
-
-            <listitem>
-              <para>或者,如果使用properties文件来配置FreeMarker
-              (<literal>*.properties</literal> 文件或者
-              <literal>java.util.Properties</literal> 对象),添加:</para>
-
-              <programlisting role="unspecified">incompatible_improvements=2.3.22</programlisting>
-            </listitem>
-
-            <listitem>
-              <para>或者,如果通过 <literal>FreemarkerServlet</literal> 
-			  来配置FreeMarker,那么将 <literal>init-param</literal> 
-			  添加到 <literal>web.xml</literal> 中:</para>
-
-              <programlisting role="unspecified">&lt;init-param&gt;
-    &lt;param-name&gt;incompatible_improvements&lt;/param-name&gt;
-    &lt;param-value&gt;2.3.22&lt;/param-value&gt;
-&lt;/init-param&gt;</programlisting>
-            </listitem>
-          </itemizedlist>
-
-          <para>但是, 在应用程序中 <emphasis>如果设置了 
-		  <literal>object_wrapper</literal></emphasis> 
-		  (也就是 <literal>Configuration.setObjectWrapper(ObjectWrapper)</literal>),
-          那么要知道很重要的一点,<literal>BeansWrapper</literal> 和它的子类(最重要的是,
-          <literal>DefaultObjectWrapper</literal>) 有它们自己独立的
-          <literal>incompatibleImprovements</literal> 属性,还有一些修复/改进会被它激活,
-		  而不是通过 <literal>Configuration</literal> 的相似设置。
-		  如果你没有在任何地方设置过 <literal>object_wrapper</literal>,那么不需要知道这点,
-		  因为,和 <literal>Configuration</literal> 一样, 
-		  默认的 <literal>object_wrapper</literal> 也有相同的 <quote>不兼容改进</quote>。
-		  但是,如果设置了 <literal>object_wrapper</literal>,
-		  那么就不要忘了设置 <literal>ObjectWrapper</literal> 自己的
-		  <literal>incompatibleImprovements</literal> 属性,此外还有
-		  <literal>Configuration</literal>。(请注意,对于 <literal>Configuration</literal> 来说,
-		  有不同的 <quote>不兼容改进</quote> 也是可以的,而对于 <literal>ObjectWrapper</literal>,
-		  则有它自己的选择。) 至于 <literal>DefaultObjectWrapper</literal>
-		  (对于 <literal>BeansWrapper</literal> 也是一样的,只是不同的类名而已) <link
-          linkend="topic.setDefaultObjectWrapperIcIIndividually">参看这里如何来设置它</link>。</para>
-        </section>
-      </section>
-    </chapter>
-
-    <chapter xml:id="pgui_misc">
-      <title>其它</title>
-
-      <para>这只是一个介绍性的导引,可以查看 <olink
-      targetdoc="api">FreeMarker Java API 文档</olink> 获取详细信息。</para>
-
-      <section xml:id="pgui_misc_var">
-        <title>变量,范围</title>
-
-        <indexterm>
-          <primary>variables</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>variable scopes</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>scopes</primary>
-        </indexterm>
-
-        <para>本章介绍当模板在访问变量时发生了什么事情,还有变量是如何存储的。</para>
-
-        <para>当调用 <literal>Template.process</literal> 方法时,它会在方法内部创建一个
-        <literal>Environment</literal> 对象,在 <literal>process</literal> 返回之前一直使用。
-		该对象存储模板执行时的运行状态信息。除了这些,它还存储由模板中指令,如
-        <literal>assign</literal>, <literal>macro</literal>,
-        <literal>local</literal> 或 <literal>global</literal> 创建的变量。
-		它不会尝试修改传递给 <literal>process</literal> 的数据模型对象,
-		也不会创建或替换存储在配置中的共享变量。</para>
-
-        <para>当你想要读取一个变量时,FreeMarker 将会以这种顺序来查找,
-		直到发现了完全匹配的的变量名称才会停下来:</para>
-
-        <orderedlist>
-          <listitem>
-            <para>在 Environment 中:</para>
-
-            <orderedlist>
-              <listitem>
-                <para>如果在循环中,在循环变量的集合中。
-				循环变量是由如 <literal>list</literal> 等指令来创建的。</para>
-              </listitem>
-
-              <listitem>
-                <para>如果在宏中,在宏的局部变量集合中。
-				局部变量可以由 <literal>local</literal> 指令创建。
-				而且,宏的参数也是局部变量。</para>
-              </listitem>
-
-              <listitem>
-                <para>在当前的 <link 
-				linkend="dgui_misc_namespace">命名空间</link> 中。
-				可以使用 <literal>assign</literal> 
-				指令将变量放到一个命名空间中。</para>
-              </listitem>
-
-              <listitem>
-                <para>在由 <literal>global</literal> 指令创建的变量集合中。
-				FTL将它们视为数据模型的普通成员变量一样来控制它们。
-				也就是说,它们在所有的命名空间中都可见,
-				你也可以像访问一个数据模型中的数据一样来访问它们。</para>
-              </listitem>
-            </orderedlist>
-          </listitem>
-
-          <listitem>
-            <para>在传递给 <literal>process</literal> 方法的数据模型对象中。</para>
-          </listitem>
-
-          <listitem>
-            <para>在 <literal>Configuration</literal> 对象存储的共享变量集合中。</para>
-          </listitem>
-        </orderedlist>
-
-        <para>在实际操作中,来自模板设计者的观点是这6种情况应该只有4种,
-		因为从那种观点来看,后面3种(由 <literal>global</literal> 创建的变量,
-		真实的数据模型对象,共享变量)共同构成了全局变量的集合。</para>
-
-        <para>请注意,在FTL中可以从一个特定层面获取 <link 
-		linkend="ref_specvar">特定变量</link>。</para>
-      </section>
-
-      <section xml:id="pgui_misc_charset">
-        <title>字符集问题</title>
-
-        <indexterm>
-          <primary>charset</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>encoding</primary>
-        </indexterm>
-
-        <para>像其它大多数的Java应用程序一样,FreeMarker使用 "<link 
-		linkend="gloss.unicode">UNICODE</link> 文本"(UTF-16)来工作。
-		不过,也有必须处理 <link linkend="gloss.charset">字符集</link> 的情况,
-		因为它不得不和外界交换数据,这就会使用到很多字符集。</para>
-
-        <section>
-          <title>输入的字符集</title>
-
-          <para>当 FreeMarker 要加载模板文件(或没有解析的文本文件)时,
-		  那就必须要知道文件使用的字符集,因为文件的存储是原生的字节序列。
-		  可以使用 <literal>encoding</literal> <link 
-		  linkend="pgui_config_settings">配置</link> 来确定字符集。
-		  这个配置项只在 FreeMarker 使用 <literal>Configuration</literal> 
-		  对象的 <literal>getTemplate</literal> 
-		  方法加载模板(解析过的或没有解析过的)时起作用。请注意 <link 
-		  linkend="ref.directive.include"><literal>include</literal> 指令 </link> 
-		  在内部也使用了这个方法,所以 <literal>encoding</literal> 
-		  的值对一个已经加载的模板,而且如果这个模板包含 <literal>include</literal> 
-		  指令的调用来说很重要。</para>
-
-          <para><literal>encoding</literal> 配置的getter和setter方法在第一个(配置)层面很特殊。
-		  getter方法猜想返回值是基于 <literal>Locale</literal>(本地化,译者注)传递的参数;
-		  它在地图区域编码表(称为编码地图)中查询编码,如果没有找到该区域,就返回默认编码。
-		  可以使用配置对象的 <literal>setEncoding(Locale locale, String encoding)</literal> 
-		  方法来填充编码表;编码表初始化时是空的。默认的初始编码是系统属性 
-		  <literal>file.encoding</literal> 的值,但是可以通过 
-		  <literal>setDefaultEncoding</literal> 方法来设置一个不同的默认值,而不是依赖它。
-		  对于新项目来说,默认的编码设置就是 <literal>utf-8</literal>。</para>
-
-          <para>也可以在模板层或运行环境层(当指定编码值作为 <literal>getTemplate</literal> 
-		  方法的参数时,应该在模板层覆盖 <literal>encoding</literal> 设置)直接给定值来覆盖 
-		  <literal>encoding</literal> 的设置。如果不覆盖它,那么 <literal>locale</literal> 
-		  设置的有效值将会是 <literal>configuration.getEncoding(Locale)</literal> 方法的返回值。</para>
-
-          <para>而且,代替这种基于字符集猜测的机制,也可以在模板文件中使用
-		  <link linkend="ref.directive.ftl"><link
-          linkend="ref.directive.ftl"><literal>ftl</literal></link>
-          指令</link>, 比如 <literal>&lt;#ftl
-          encoding="utf-8"&gt;</literal> 来指定特定的字符集。</para>
-
-          <para>请注意,模板使用的字符集和模板生成的输出内容的字符集是独立的
-		  (除非包含 FreeMarker 的软件故意将设置输出内容的字符集和模板字符集设置成相同的)。</para>
-        </section>
-
-        <section>
-          <title>输出的字符集</title>
-
-          <note>
-            <para><literal>output_encoding</literal> 设置/参数和 <link 
-			linkend="ref_builtin_url">内建函数<literal>url</literal></link> 
-			从FreeMarker 2.3.1版本开始才可以使用,而在2.3以前的版本中是不存在的。</para>
-          </note>
-
-          <para><indexterm>
-              <primary>output encoding</primary>
-            </indexterm><indexterm>
-              <primary>output charset</primary>
-            </indexterm>原则上,FreeMarker 不处理输出内容的字符集问题,
-			因为 FreeMarker 将输出内容都写入了 <literal>java.io.Writer</literal> 
-			对象中。而 <literal>Writer</literal> 
-			对象是由封装了 FreeMarker(比如Web应用框架) 的软件生成的,
-			那么输出内容的字符集就是由封装软件来控制的。而FreeMarker有一个称为
-			<literal>output_encoding</literal>(开始于 FreeMarker 2.3.1 版本之后)的设置。
-			封装软件应该使用这个设置(<literal>Writer</literal>对象使用的字符集)
-			来通知 FreeMarker 在输出中(否则 FreeMarker 不能找到它)使用哪种字符集。
-			有一些新的特性,如<link 
-			linkend="ref_builtin_url">内建函数<literal>url</literal></link>,<link 
-			linkend="ref_specvar">特殊变量<literal>output_encoding</literal></link> 
-			也利用这个信息。因此,如果封装软件没有设置字符集这个信息,
-			那么 FreeMarker 需要知道输出字符集的特性就不能被利用了。</para>
-
-          <para>如果你使用 FreeMarker 来编写软件,
-		  你也许想知道在输出内容中到底选择了哪种字符集。
-		  当然这取决于运行 FreeMarker 输出内容的计算机本身,
-		  但是如果用户对这个问题可以变通,
-		  那么通用的实践是使用模板文件的字符集作为输出的字符集,或者使用UTF-8。
-		  通常使用UTF-8是最佳的实践,因为任意的文本可能来自数据模型,
-		  那就可能包含不能被模板字符集所编码的字符。</para>
-
-          <para>如果使用了 
-		  <literal>Template.createProcessingEnvironment(<replaceable>...</replaceable>)</literal> 
-		  和 <literal>Environment.process(<replaceable>...</replaceable>)</literal> 方法来代替 
-		  <literal>Template.process(<replaceable>...</replaceable>)</literal> 方法,
-		  FreeMarker 的设置可以对任意独立执行的模板进行。
-		  因此,你可以对每个独立执行的模板设置 <literal>output_encoding</literal> 信息:</para>
-
-          <programlisting role="unspecified">Writer w = new OutputStreamWriter(out, outputCharset);
-Environment env = template.createProcessingEnvironment(dataModel, w);
-env.setOutputEncoding(outputCharset);
-env.process();</programlisting>
-        </section>
-      </section>
-
-      <section xml:id="pgui_misc_multithreading">
-        <title>多线程</title>
-
-        <indexterm>
-          <primary>multithreading</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>thread-safety</primary>
-        </indexterm>
-
-        <para>在多线程运行环境中, <literal>Configuration</literal> 实例,
-		<literal>Template</literal> 实例和数据模型应该是永远不能改变(只读)的对象。
-		也就是说,创建和初始化它们(如使用 <literal>set<replaceable>...</replaceable></literal> 
-		方法)之后,就不能再修改它们了(比如不能再次调用 
-		<literal>set<replaceable>...</replaceable></literal> 方法)。
-		这就允许我们在多线程环境中避免代价很大的同步锁问题。要小心 <literal>Template</literal> 实例;
-		当使用了 <literal>Configuration.getTemplate</literal> 方法获得 
-		<literal>Template</literal> 一个实例时,也许得到的是从模板缓存中缓存的实例,
-		这些实例都已经被其他线程使用了,所以不要调用它们的 
-		<literal>set<replaceable>...</replaceable></literal> 方法
-		(当然调用 <literal>process</literal> 方法还是不错的)。</para>
-
-        <para>如果只从 <emphasis>同一个</emphasis> 独立线程中访问所有对象,
-		那么上面所述的限制将不会起作用。</para>
-
-        <para>使用FTL来修改数据模型对象或者 <link 
-		linkend="pgui_config_sharedvariables">共享变量</link> 是不太可能的,
-		除非将方法(或其他对象)放到数据模型中来做。
-		我们不鼓励你编写修改数据模型对象或共享变量的方法。多试试使用存储在环境对象
-		(这个对象是为独立的 <literal>Template.process</literal> 调用而创建的,
-		用来存储模板处理的运行状态)中的变量,所以最好不要修改那些由多线程使用的数据。
-		要获取更多信息,请阅读:<xref linkend="pgui_misc_var"/></para>
-      </section>
-
-      <section xml:id="pgui_misc_beanwrapper">
-        <title>Bean的包装</title>
-
-        <indexterm>
-          <primary>wrapping</primary>
-
-          <secondary>reflection</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>wrapping</primary>
-
-          <secondary>beans</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>beans</primary>
-
-          <secondary>wrapping</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>BeansWrapper</primary>
-        </indexterm>
-
-        <note>
-          <para>直接使用 <literal>BeansWrapper</literal> 是不推荐的。
-		  而可以使用它的子类 <literal>DefaultObjectWrapper</literal> 
-		  来代替,要确保它的 <literal>incompatibleImprovements</literal> 
-		  属性至少是2.3.22。<literal>DefaultObjectWrapper</literal> 
-		  给出了干净的数据模型(很少的容易混淆的多类型的FTL值)而且通常速度很快。<link 
-		  linkend="pgui_datamodel_defaultObjectWrapper">关于更多
-          DefaultObjectWrapper 可以参看这里...</link></para>
-        </note>
-
-        <para><literal>freemarker.ext.beans.BeansWrapper</literal> 是一个<link 
-		linkend="pgui_datamodel_objectWrapper">对象包装器</link>,
-		最初加到FreeMarker中是为了将任意的POJO(Plan Old Java Objects,普通的Java对象)
-		包装成 <literal>TemplateModel</literal> 接口类型。
-		这样它就可以以正常的方式来进行处理,事实上 <literal>DefaultObjectWrapper</literal> 
-		本身是 <literal>BeansWrapper</literal> 的扩展类。
-		这里描述的所有东西对 <literal>DefaultObjectWrapper</literal> 都是适用的,
-		除了 <literal>DefaultObjectWrapper</literal> 会用到 
-		<literal>freemarker.template.Simple<replaceable>Xxx</replaceable></literal> 
-		类包装的<literal>String</literal>,<literal>Number</literal>,
-		<literal>Date</literal>,<literal>array</literal>,
-		<literal>Collection</literal>(如<literal>List</literal>),
-		<literal>Map</literal>,<literal>Boolean</literal> 和 
-		<literal>Iterator</literal>对象,会用 <literal>freemarker.ext.dom.NodeModel</literal> 
-		来包装W3C的DOM结点(<link linkend="xgui">更多关于包装的W3C DOM 可以参考这里...</link>),
-		所以上述这些描述的规则不适用。</para>
-
-        <para>当出现下面这些情况时,
-		你会想使用 <literal>BeansWrapper</literal> 包装器来代替 
-		<literal>DefaultObjectWrapper</literal>:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>在模板执行期间,数据模型中的 <literal>Collection</literal> 
-			和 <literal>Map</literal> 应该被允许修改。
-			(<literal>DefaultObjectWrapper</literal> 会阻止这样做,
-			因为当它包装对象时创建了数据集合的拷贝,而这些拷贝都是只读的。)</para>
-          </listitem>
-
-          <listitem>
-            <para>如果 <literal>array</literal>,<literal>Collection</literal> 
-			和 <literal>Map</literal> 对象的标识符当在模板中被传递到被包装对象的方法时,
-			必须被保留下来。也就是说,那些方法必须得到之前包装好的同类对象。</para>
-          </listitem>
-
-          <listitem>
-            <para>如果在之前列出的Java API中的类(如 <literal>String</literal>,
-			<literal>Map</literal>,<literal>List</literal> 等)应该在模板中可见。
-			还有 <literal>BeansWrapper</literal>,默认情况下它们是不可见的,
-			但是可以设置获取的可见程度(后面将会介绍)。请注意这是一个不好的实践,
-			尽量去使用 <link linkend="ref_builtins">内建函数</link>
-			(如<literal>foo?size</literal>,<literal>foo?upper_case</literal>,
-			<literal>foo?replace('_', '-')</literal> 等)来代替Java API的使用。</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>下面是对 <literal>BeansWrapper</literal> 创建的 
-		<literal>TemplateModel</literal> 对象进行的总结。为了后续的讨论,
-		这里我们假设在包装之前对象都称为 <literal>obj</literal>,
-		而包装的后称为 <literal>model</literal>。</para>
-
-        <section xml:id="beanswrapper_hash">
-          <title>模板哈希表模型功能(TemplateHashModel functionality)</title>
-
-          <para>所有的对象都将被包装成 <literal>TemplateHashModel</literal> 类型,
-		  进而可以获取出JavaBean对象中的属性和方法。这样,
-		  就可以在模板中使用 <literal>model.foo</literal> 的形式来调用 
-		  <literal>obj.getFoo()</literal> 方法或 <literal>obj.isFoo()</literal> 方法了。
-		  (要注意公有的属性直接是不可见的,必须为它们编写getter方法才行)
-		  公有方法通过哈希表模型来取得,就像模板方法模型那样,
-		  因此可以使用 <literal>model.doBar()</literal> 来调用 
-		  <literal>object.doBar()</literal>。下面我们来更多讨论一下方法模型功能。</para>
-
-          <para>如果请求的键值不能映射到一个bean的属性或方法时,
-		  那么框架将试图定位到"通用的get方法",这个方法的签名是 
-		  public <literal><replaceable>any-return-type</replaceable> get(String)</literal> 或 
-		  public <literal><replaceable>any-return-type</replaceable> get(Object)</literal>,
-		  使用请求键值来调用它们。请注意,这样就使得访问 <literal>java.util.Map</literal> 
-		  和其他类似类型的键值对非常便利。只要map的键是 <literal>String</literal> 类型的,
-		  属性和方法名可以在映射中查到。(有一种解决方法可以用来避免在映射中遮挡名称,请继续来阅读。)
-		  要而且注意 <literal>java.util.ResourceBundle</literal> 对象的方法使用 
-		  <literal>getObject(String)</literal> 方法作为通用的get方法。</para>
-
-          <para>如果在 <literal>BeansWrapper</literal> 实例中调用了 
-		  <literal>setExposeFields(true)</literal> 方法,那么它仍然会暴露出类的公有的,
-		  非静态的变量,用它们作为哈希表的键和值。即如果 <literal>foo</literal> 
-		  是类 <literal>Bar</literal> 的一个公有的,非静态的变量,而 
-		  <literal>bar</literal> 是一个包装了 <literal>Bar</literal> 实例模板变量,
-		  那么表达式 <literal>bar.foo</literal> 的值将会作为 <literal>bar</literal> 
-		  对象中 <literal>foo</literal> 变量的值。所有这个类的超类中公有变量都会被暴露出来。</para>
-        </section>
-
-        <section>
-          <title>说一点安全性</title>
-
-          <para>默认情况下,一些方法不能访问,它们被认为是模板中不安全的。
-		  比如,不能使用同步方法(<literal>wait</literal>,<literal>notify</literal>,
-		  <literal>notifyAll</literal>),线程和线程组的管理方法(<literal>stop</literal>,
-		  <literal>suspend</literal>,<literal>resume</literal>,<literal>setDaemon</literal>,
-		  <literal>setPriority</literal>),反射相关方法(<literal>Field</literal>,
-		  <literal>set<replaceable>Xxx</replaceable></literal> 方法,
-		  <literal>Method.invoke</literal>,<literal>Constructor.newInstance</literal>,
-		  <literal>Class.newInstance</literal>,<literal>Class.getClassLoader</literal>等),
-		  <literal>System</literal> 和 <literal>Runtime</literal> 类中各种有危险性的方法
-		  (<literal>exec</literal>,<literal>exit</literal>,<literal>halt</literal>,
-		  <literal>load</literal>等)。<literal>BeansWrapper</literal> 也有一些安全级别
-		  (被称作"方法暴露的级别"),默认的级别被称作为 <literal>EXPOSE_SAFE</literal>,
-		  它可能对大多数应用程序来说是适用的。没有安全保证的级别称作是 
-		  <literal>EXPOSE_ALL</literal>,它允许你调用上述的不安全的方法。一个严格的级别是 
-		  <literal>EXPOSE_PROPERTIES_ONLY</literal>,它只会暴露出bean属性的getters方法。
-		  最后,一个称作是 <literal>EXPOSE_NOTHING</literal> 的级别,它不会暴露任何属性和方法。
-		  这种情况下,你可以通过哈希表模型接口访问的那些数据只是map和资源包中的项,
-		  还有,可以从通用 <literal>get(Object)</literal> 方法和 <literal>get(String)</literal> 
-		  方法调用返回的对象,所提供的受影响的对象就有这样的方法。</para>
-        </section>
-
-        <section>
-          <title>模板标量模型功能(TemplateScalarModel functionality)</title>
-
-          <para>对于 <literal>java.lang.String</literal> 对象的模型会实现 
-		  <literal>TemplateScalarModel</literal> 接口,这个接口中的 
-		  <literal>getAsString()</literal> 方法简单代替了 <literal>toString()</literal> 方法。
-		  要注意把 <literal>String</literal> 对象包装到Bean包装器中,
-		  要提供比它们作为标量时更多的功能:因为哈希表接口描述了上述所需功能,
-		  那么包装 <literal>String</literal> 的模型也会提供访问所有 
-		  <literal>String</literal> 的方法(<literal>indexOf</literal>,
-		  <literal>substring</literal> 等),尽管它们中很多都有内部的FreeMarker相同的实现,
-		  最好使用它们(<literal>s?index_of(n)</literal>,<literal>s[start..&lt;end]</literal> 等)。</para>
-        </section>
-
-        <section>
-          <title>模板数字模型功能(TemplateNumberModel functionality)</title>
-
-          <para>对于是 <literal>java.lang.Number</literal> 的实例对象的模型包装器,
-		  它们实现了 <literal>TemplateNumberModel</literal> 接口,接口中的 
-		  <literal>getAsNumber()</literal> 方法返回被包装的数字对象。
-		  请注意把 <literal>Number</literal> 对象包装到Bean包装器中,
-		  要提供比它们作为数字时更多的功能:因为哈希表接口描述了上述所需功能,
-		  那么包装 <literal>Number</literal> 的模型也会提供访问所有他们的方法。</para>
-        </section>
-
-        <section>
-          <title>模板集合模型功能(TemplateCollectionModel functionality)</title>
-
-          <para>对于本地的Java数组和其他所有实现了 <literal>java.util.Collection</literal> 
-		  接口的类的模型包装器,都实现了 <literal>TemplateCollectionModel</literal> 接口,
-		  因此也增强了使用 <literal>list</literal> 指令的附加功能。</para>
-        </section>
-
-        <section>
-          <title>模板序列模型功能(TemplateSequenceModel functionality)</title>
-
-          <para>对于本地的Java数组和其他所有实现了 <literal>java.util.List</literal> 
-		  接口的类的模型包装器,都实现了 <literal>TemplateSequenceModel</literal> 接口,
-		  这样,它们之中的元素就可以使用 <literal>model[i]</literal> 这样的语法通过索引来访问了。
-		  你也可以使用内建函数 <literal>model?size</literal> 来查询数组的长度和列表的大小。</para>
-
-          <para>而且,所有的方法都可指定的一个单独的参数,从 
-		  <literal>java.lang.Integer</literal>(即<literal>int</literal>, <literal>long</literal>, 
-		  <literal>float</literal>, <literal>double</literal>,<literal>java.lang.Object</literal>,
-		  <literal>java.lang.Number</literal>,<literal>java.lang.Integer</literal>)
-		  中通过反射方法调用,这些类也实现了这个接口。
-		  这就意味着你可以通过很方便的方式来访问被索引的bean属性:
-		  <literal>model.foo[i]</literal> 将会翻译为 <literal>obj.getFoo(i)</literal>。</para>
-        </section>
-
-        <section xml:id="beanswrapper_method">
-          <title>模板方法模型功能(TemplateMethodModel functionality)</title>
-
-          <para>一个对象的所有方法作为 <literal>TemplateMethodModelEx</literal> 对象的表述,
-		  它们在对象模型的方法名中使用哈希表的键来访问。当使用 
-		  <literal>model.<replaceable>method</replaceable>(<replaceable>arg1</replaceable>,
-          <replaceable>arg2</replaceable>,
-          <replaceable>...</replaceable>)</literal> 来调用方法时,形参被作为模板模型传递给方法。
-		  方法首先不会包装它们,后面我们会说到解包的详细内容。
-		  这些不被包装的参数之后被实际方法来调用。以防止方法被重载,
-		  许多特定的方法将会被选择使用相同的规则,也就是Java编译器从一些重载的方法中选择一个方法。
-		  以防止没有方法签名匹配传递的参数,或者没有方法可以被无歧义地选择,
-		  将会抛出 <literal>TemplateModelException</literal> 异常。</para>
-
-          <para>返回值类型为 <literal>void</literal> 的方法返回 
-		  <literal>TemplateModel.NOTHING</literal>,那么它们就可以使用 
-		  <literal>${obj.method(args)}</literal> 形式的语法被安全地调用。</para>
-
-          <para><literal>java.util.Map</literal> 实例的模型仍然实现了 
-		  <literal>TemplateMethodModelEx</literal> 接口,作为调用它们 
-		  <literal>get()</literal> 方法的一种方式。正如前面所讨论的那样,
-		  你可以使用哈希表功能来访问"get"方法,但是它有一些缺点:
-		  因为第一个属性和方法名会被键名来检查,所以执行过慢;
-		  属性,方法名相冲突的键将会被隐藏;最终这种方法中你只可使用 
-		  <literal>String</literal> 类型的键。对比一下,调用 
-		  <literal>model(key)</literal> 方法,将直接翻译为 
-		  <literal>model.get(key)</literal>:因为没有属性和方法名的查找,
-		  速度会很快;不容易被隐藏;最终对非字符串的键也能正常处理,
-		  因为参数没有被包装,只是被普通的方法调用。实际上,
-		  <literal>Map</literal> 中的 <literal>model(key)</literal> 和 
-		  <literal>model.get(key)</literal> 是相等的,只是写起来很短罢了。</para>
-
-          <para><literal>java.util.ResourceBundle</literal> 类的模型也实现了 
-		  <literal>TemplateMethodModelEx</literal> 接口,
-		  作为一种访问资源和信息格式化的方便形式。对资源包的单参数调用,
-		  将会取回名称和未包装参数的 <literal>toString()</literal> 方法返回值一致的资源。
-		  对资源包的多参数调用的情况和单参数一样,但是它会将参数作为格式化的模式传递给 
-		  <literal>java.text.MessageFormat</literal>,在第二个和后面的作为格式化的参数中使用未包装的值。
-		  <literal>MessageFormat</literal> 对象将会使用它们原本的本地化资源包来初始化。</para>
-        </section>
-
-        <section>
-          <title>解包规则</title>
-
-          <para>当从模板中调用Java方法时,它的参数需要从模板模型转换回Java对象。
-		  假设目标类型(方法常规参数被声明的类型)是用来 <literal>T</literal> 代表的,
-		  下面的规则将会按下述的顺序进行依次尝试:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para>对包装器来说,如果模型是空模型,
-			  就返回Java中的 <literal>null</literal>。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型实现了 <literal>AdapterTemplateModel</literal> 接口,
-			  如果它是 <literal>T</literal> 的实例,
-			  或者它是一个数字而且可以使用下面第三点描述的数字强制转换成 <literal>T</literal>,
-			  那么 <literal>model.getAdaptedObject(T)</literal> 的结果会返回。
-			  <phrase role="forProgrammers">由BeansWrapper创建的所有方法是AdapterTemplateModel的实现,
-			  所以由BeansWrapper为基本的Java对象创建的展开模型通常不如初始的Java对象。</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型实现了已经废弃的 <literal>WrapperTemplateModel</literal> 接口,
-			  如果它是 <literal>T</literal> 的实例,
-			  或者它是一个数字而且可以使用下面第二点描述的数字强制转换成 
-			  <literal>T</literal> ,那么 <literal>model.getWrappedObject()</literal> 
-			  方法的结果会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是 <literal>java.lang.String</literal> 类型,
-			  那么如果模型实现了 <literal>TemplateScalarModel</literal> 接口,它的字符串值将会返回。
-              <phrase role="forProgrammers">请注意,如果模型没有实现接口,
-			  我们不能尝试使用String.valueOf(model)方法自动转换模型到String类型。
-			  这里不得不使用内建函数?string明确地用字符串来处理非标量。</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是原始的数字类型或者是可由 
-			  <literal>T</literal> 指定的 <literal>java.lang.Number</literal> 
-			  类型,还有模型实现了 <literal>TemplateNumberModel</literal> 接口,
-			  如果它是 <literal>T</literal> 的实例或者是它的装箱类型
-			  (如果 <literal>T</literal> 是原始类型),那么它的数字值会返回。
-			  否则,如果 <literal>T</literal> 是一个Java内建的数字类型
-			  (原始类型或是 <literal>java.lang.Number</literal> 的标准子类,
-			  包括 <literal>BigInteger</literal> 和 <literal>BigDecimal</literal>),
-			  类型 <literal>T</literal> 
-			  的一个新对象或是它的装箱类型会由数字模型的适当强制的值来生成。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是 <literal>boolean</literal> 值或
-              <literal>java.lang.Boolean</literal> 类型,模型实现了
-              <literal>TemplateBooleanModel</literal> 接口,那么布尔值将会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是
-              <literal>java.util.Map</literal> 类型,模型实现了
-              <literal>TemplateHashModel</literal> 接口,
-			  那么一个哈希表模型的特殊Map表示对象将会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是
-              <literal>java.util.List</literal> 类型,模型实现了
-              <literal>TemplateSequenceModel</literal> 接口,
-			  那么一个序列模型的特殊List表示对象将会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是
-              <literal>java.util.Set</literal> 类型,模型实现了
-              <literal>TemplateCollectionModel</literal> 接口,
-			  那么集合模型的一个特殊Set表示对象将会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是
-              <literal>java.util.Collection</literal> 或
-              <literal>java.lang.Iterable</literal> 类型,模型实现了
-              <literal>TemplateCollectionModel</literal> 或
-              <literal>TemplateSequenceModel</literal> 接口,
-			  那么集合或序列模型(各自地)一个特殊的Set或List表示对象将会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是Java数组类型,模型实现了 
-			  <literal>TemplateSequenceModel</literal> 接口,
-			  那么一个新的指定类型的数组将会创建,
-			  它其中的元素使用数组的组件类型作为 <literal>T</literal>,
-			  递归展开到数组中。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 是 <literal>char</literal> 或
-              <literal>java.lang.Character</literal> 类型,模型实现了
-              <literal>TemplateScalarModel</literal> 接口,
-			  它的字符串表示中包含精确的一个字符,那么一个
-              <literal>java.lang.Character</literal> 类型的值将会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果 <literal>T</literal> 定义的是 
-			  <literal>java.util.Date</literal> 类型,模型实现了
-              <literal>TemplateDateModel</literal> 接口,
-			  而且它的日期值是 <literal>T</literal> 的实例,
-			  那么这个日期值将会返回。</para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是数字模型,而且它的数字值是 <literal>T</literal> 
-			  的实例,那么数字值就会返回。<phrase role="forProgrammers">
-			  你可以得到一个实现了自定义接口的
-			  java.lang.Number类型的自定义子类,也许T就是那个接口。(*)</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是日期类型,而且它的日期值是 <literal>T</literal> 的实例,
-			  那么日期值将会返回。<phrase role="forProgrammers">类似的考虑为(*)</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是标量类型,而且 <literal>T</literal> 
-			  可以从 <literal>java.lang.String</literal> 类型来定义,
-			  那么字符串值将会返回。<phrase role="forProgrammers">
-			  这种情况涵盖T是java.lang.Object, 
-			  java.lang.Comparable和java.io.Serializable类型。(**)</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是布尔类型,而且 <literal>T</literal> 
-			  可以从 <literal>java.lang.Boolean</literal> 类型来定义,
-			  那么布尔值将会返回。
-			  <phrase role="forProgrammers">和(**)是相同的</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是哈希表类型,而且 <literal>T</literal> 
-			  可以从 <literal>freemarker.ext.beans.HashAdapter</literal> 类型来定义,
-			  那么一个哈希表适配器将会返回。
-			  <phrase role="forProgrammers">和(**)是相同的</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是序列类型,而且 <literal>T</literal> 
-			  可以从 <literal>freemarker.ext.beans.SequenceAdapter</literal> 类型来定义,
-			  那么一个序列适配器将会返回。
-			  <phrase role="forProgrammers">和(**)是相同的</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是集合类型,而且 <literal>T</literal> 
-			  可以从 <literal>freemarker.ext.beans.SetAdapter</literal> 类型来定义,
-			  那么集合的set适配器将会返回。
-			  <phrase role="forProgrammers">和(**)是相同的</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>如果模型是 <literal>T</literal> 的实例,那么模型本身将会返回。
-			  <phrase role="forProgrammers">这种情况涵盖方法明确地声明一个 FreeMarker 特定模型接口,
-			  而且允许返回指令,当java.lang.Object被请求时允许返回方法和转换的模型。</phrase></para>
-            </listitem>
-
-            <listitem>
-              <para>意味着没有可能转换的异常被抛出。</para>
-            </listitem>
-          </itemizedlist>
-        </section>
-
-        <section>
-          <title>访问静态方法</title>
-
-          <indexterm>
-            <primary>static method</primary>
-
-            <secondary>accessing from templates</secondary>
-          </indexterm>
-
-          <para>从 <literal>BeansWrapper.getStaticModels()</literal> 方法返回的
-		  <literal>TemplateHashModel</literal> 
-		  可以用来创建哈希表模型来访问任意类的静态方法和字段。</para>
-
-          <programlisting role="unspecified">BeansWrapper wrapper = BeansWrapper.getDefaultInstance();
-TemplateHashModel staticModels = wrapper.getStaticModels();
-TemplateHashModel fileStatics =
-    (TemplateHashModel) staticModels.get("java.io.File");</programlisting>
-
-          <para>之后就可以得到模板的哈希表模型,它会暴露所有 
-		  <literal>java.lang.System</literal> 类的静态方法和静态字段
-		  (final类型和非final类型)作为哈希表的键。
-		  设想你已经将之前的模型放到根root模型中了:</para>
-
-          <programlisting role="unspecified">root.put("File", fileStatics);</programlisting>
-
-          <para>从现在开始,你可以在模板中使用 <literal>${File.SEPARATOR}</literal> 
-		  来插入文件分隔符,或者你可以列出所有文件系统中的根元素,通过:</para>
-
-          <programlisting role="template">&lt;#list File.listRoots() as fileSystemRoot&gt;...&lt;/#list&gt;</programlisting>
-
-          <para>当然,你必须小心这个模型所带来的潜在的安全问题。</para>
-
-          <para>你可以给模板作者完全的自由,
-		  不管它们通过将静态方法的哈希表放到模板的根模型中,
-		  来使用哪种类的静态方法,如用如下方式:</para>
-
-          <programlisting role="unspecified">root.put("statics", BeansWrapper.getDefaultInstance().getStaticModels());</programlisting>
-
-          <para>如果它被用作是以类名为键的哈希表,
-		  这个对象暴露的只是任意类的静态方法。那么你可以在模板中使用如 
-		  <literal>${statics["java.lang.System"].currentTimeMillis()}</literal> 
-		  这样的表达式。请注意,这样会有更多的安全隐患,比如,
-		  如果方法暴露级别对 <literal>EXPOSE_ALL</literal> 是很弱的,
-		  那么某些人可以使用这个模型调用 <literal>System.exit()</literal> 方法。</para>
-
-          <para>请注意,在上述的示例中,我们通常使用默认的 
-		  <literal>BeansWrapper</literal> 实例。这是一个方便使用的静态包装器实例,
-		  你可以在很多情况下使用。特别是你想修改一些属性
-		  (比如模型缓存,安全级别,或者是空模型对象表示)时,
-		  你也可以自由地来创建自己的 <literal>BeansWrapper</literal> 实例,
-		  然后用它们来代替默认包装器。</para>
-        </section>
-
-        <section xml:id="jdk_15_enums">
-          <title>访问枚举类型</title>
-
-          <indexterm>
-            <primary>enum</primary>
-          </indexterm>
-
-          <para>在JRE 1.5版本之后,从方法 <literal>BeansWrapper.getEnumModels()</literal> 
-		  返回的 <literal>TemplateHashModel</literal> 可以被用作创建访问枚举类型值的哈希表模型。
-		  (试图在之前JRE中调用这个方法会导致 <literal>UnsupportedOperationException</literal> 异常。)</para>
-
-          <programlisting role="unspecified">BeansWrapper wrapper = BeansWrapper.getDefaultInstance();
-TemplateHashModel enumModels = wrapper.getEnumModels();
-TemplateHashModel roundingModeEnums =
-    (TemplateHashModel) enumModels.get("java.math.RoundingMode");</programlisting>
-
-          <para>这样你就可以得到模板哈希表模型,它暴露了 
-		  <literal>java.math.RoundingMode</literal> 类所有枚举类型的值,
-		  并把它们作为哈希表的键。设想你将之前的模型已经放入root模型中了:</para>
-
-          <programlisting role="unspecified">root.put("RoundingMode", roundingModeEnums);</programlisting>
-
-          <para>现在开始,你可以在模板中使用表达式 
-		  <literal>RoundingMode.UP</literal> 来引用枚举值 <literal>UP</literal>。</para>
-
-          <para>你可以给模板作者完全的自由,不管它们使用哪种枚举类,
-		  将枚举模型的哈希表放到模板的root模型中,可以这样来做:</para>
-
-          <programlisting role="unspecified">root.put("enums", BeansWrapper.getDefaultInstance().getEnumModels());</programlisting>
-
-          <para>如果它被用作是类名作为键的哈希表,这个对象暴露了任意的枚举类。
-		  那么可以在模板中使用如 
-		  <literal>${enums["java.math.RoundingMode"].UP}</literal> 的表达式。</para>
-
-          <para>被暴露的枚举值可以被用作是标量(它们会委派它们的 
-		  <literal>toString()</literal> 方法),也可以用在相同或不同的比较中。</para>
-
-          <para>请注意,在上述的例子中,我们通常使用默认的 
-		  <literal>BeansWrapper</literal> 实例。这是一个方便使用的静态包装器实例,
-		  你可以在很多情况下使用。特别是你想修改一些属性
-		  (比如模型缓存,安全级别,或者是空模型对象表示)时,
-		  你也可以自由地来创建自己的 <literal>BeansWrapper</literal> 实例,
-		  然后用它们来代替默认包装器。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_misc_logging">
-        <title>日志</title>
-
-        <indexterm>
-          <primary>logging</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>SLF4J</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>Log4j2</primary>
-        </indexterm>
-
-        <section>
-          <title>日志库选择</title>
-
-          <para>简而言之,在现代(比如2015年)的应用程序中,
-		  记录日志推荐使用SLF4J API。
-		  要让 FreeMarker 2.3.x. 使用SLF4J,在项目中加入依赖 
-		  <literal>org.slf4j:log4j-over-slf4j</literal> 即可,
-		  要确保 <literal>log4j:log4j</literal>
-		  不能存在。(从 FreeMarker 2.4.x 开始,尽管没有什么害处,
-		  但也不再需要 <literal>log4j-over-slf4j</literal> 了。)</para>
-
-          <para>如果你对这些细节好奇,或者不能使用SLF4J,那么就继续阅读吧...</para>
-
-          <para>FreeMarker 整合了如下的日志包:<link 
-		  xlink:href="http://www.slf4j.org/">SLF4J</link>,<link 
-		  xlink:href="http://commons.apache.org/logging/">Apache Commons Logging</link>,<link 
-		  xlink:href="http://jakarta.apache.org/log4j">Log4J</link> 1.x,<link 
-		  xlink:href="http://jakarta.apache.org/avalon/logkit">Avalon LogKit</link> 和 <link 
-		  xlink:href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
-		  <literal>java.util.logging</literal></link>。默认情况下,
-		  FreeMarker(在2.3.x版本下)会按如下顺序来查找日志包,
-		  而且会自动使用第一个发现的包:<remark>[2.4 - un-remark this] SLF4J, Apache Commons Logging, </remark>
-		  LOG4J(从2.3.22开始,如果正确安装了<literal>log4j-over-slf4j</literal>,则会使用SLF4J来代替),
-		  Apache Avalon LogKit, <literal>java.util.logging</literal>。
-		  正如你所见,Log4j有最高的优先级。<literal>org.apache.log4j.Logger</literal> 
-		  类会检测Log4j的存在,那么也就是说,像<literal>log4j-over-slf4j</literal> 或 
-          <literal>log4j-1.2-api</literal>,Log4j重定向也会有最高优先级。</para>
-
-          <para>在 FreeMarker 2.4 版本之前,因为向后兼容性的限制,
-		  SLF4J和Apache Commons Logging不会被自动搜索。但是如果你正确安装了 
-		  <literal>org.slf4j:log4j-over-slf4j</literal>(也就意味着,
-		  在类路径下没有真实的Log4j,SLF4J有一个像 <literal>logback-classic</literal> 
-		  的支持实现),那么FreeMarker会直接使用SLF4J API来代替Log4j API
-		  (从FreeMarker 2.3.22版本开始)。</para>
-
-          <para>请注意,应用Log4j2日志有个相似的技巧:如果 
-		  <literal>org.apache.logging.log4j:log4j-1.2-api</literal> 可用,
-		  FreeMarker 2.3.x会使用它,因为它看起来就像Log4j,
-		  但是所有的消息都会自动到Log4j2中。</para>
-
-          <para>如果自动检测没有给出你想要的结果,那么你可以设置系统属性 
-          <literal>org.freemarker.loggerLibrary</literal> 来明确选择
-		  (从2.3.22版本开始)一个日志库,比如:</para>
-
-          <programlisting role="unspecified">java <replaceable>...</replaceable> -Dorg.freemarker.loggerLibrary=SLF4J</programlisting>
-
-          <para>系统属性支持的值有:
-          <literal>SLF4J</literal>, <literal>CommonsLogging</literal>,
-          <literal>JUL</literal> (即 <literal>java.util.logging</literal>),
-          <literal>Avalon</literal>, <literal>auto</literal> (默认行为), 
-		  <literal>none</literal> (关闭日志)。</para>
-
-          <para>请注意,为了可靠的运行,系统属性应该在JVM启动时(向上面那样)就该设置好,
-		  而不是在Java代码之后。</para>
-
-          <para>推荐使用SLF4J,因为它在 FreeMarker 中运行的更好,
-		  也是因为从 FreeMarker 2.4 版本开始它有自动检测的最高优先级。</para>
-        </section>
-
-        <section>
-          <title>日志分类</title>
-
-          <para>由FreeMarker产生的所有日志信息会被记录到名称由 
-		  <literal>freemarker.</literal>开头的日志记录器中。
-		  现在被使用的记录器是:</para>
-
-          <informaltable border="1">
-            <thead>
-              <tr>
-                <th>日志分类名称</th>
-
-                <th>目标</th>
-              </tr>
-            </thead>
-
-            <tbody>
-              <tr>
-                <td><literal>freemarker.beans</literal></td>
-
-                <td>记录Beans包装器模块的日志信息。</td>
-              </tr>
-
-              <tr>
-                <td><literal>freemarker.cache</literal></td>
-
-                <td>记录模板加载和缓存相关的日志信息。</td>
-              </tr>
-
-              <tr>
-                <td><literal>freemarker.runtime</literal></td>
-
-                <td>记录在模板执行期间的和特定分类无关的相关信息。
-				更重要的是,它会记录模板异常并在模板处理期间抛出
-				(但它却应该在现行的应用程序中禁用;稍后将会解释)。</td>
-              </tr>
-
-              <tr>
-                <td><literal>freemarker.runtime.attempt</literal></td>
-
-                <td>记录在模板执行期间抛出的模板异常日志信息,
-				但是是开启DEBUG严重级别,并由 
-				<literal>attempt</literal>/<literal>recover</literal> 指令捕捉。
-				请注意,该异常也会被记录到正常的日志记录器中
-				(比如<literal>freemarker.runtime</literal>)。</td>
-              </tr>
-
-              <tr>
-                <td><literal>freemarker.servlet</literal></td>
-
-                <td>记录来自 <literal>FreemarkerServlet</literal> 类的消息。</td>
-              </tr>
-
-              <tr>
-                <td><literal>freemarker.jsp</literal></td>
-
-                <td>记录FreeMarker JSP 支持的消息。</td>
-              </tr>
-            </tbody>
-          </informaltable>
-
-          <para>FreeMarker 会在模板执行期间使用 
-		  <literal>freemarker.runtime</literal> 记录异常,即便异常继续增加,最终由 
-		  <literal>Template.process</literal> 或 <literal>Environment.process</literal> 抛出。
-		  (那些都是从应用程序或框架中调用模板时的API调用。)
-		  良好的应用程序会记录它们抛出的异常,极少数情况下是处理它们而不去记录日志。
-		  但是FreeMarker已经记录了异常,那么就会得到比期望的多一条日志记录。
-		  要修复这个问题(从2.3.22版本开始),可以设置 <literal>log_template_exceptions</literal>
-          (<literal>Configurable.setLogTemplateExceptions(boolean)</literal>)
-          为 <literal>false</literal>。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_misc_servlet">
-        <title>在Servlet中使用FreeMarker</title>
-
-        <anchor xml:id="topic.servlet"/>
-
-        <indexterm>
-          <primary>Servlet</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>HTTP</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>JSP</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>Model 2</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>Struts</primary>
-        </indexterm>
-
-        <indexterm>
-          <primary>Web应用框架</primary>
-        </indexterm>
-
-        <para>作为基础了解,在web应用程序范畴内使用 FreeMarker 和其它并没有什么不同;
-		FreeMarker将它的输出写入传递给 <literal>Template.process</literal> 方法的 
-		<literal>Writer</literal> 对象,它不关心 <literal>Writer</literal> 
-		将输出写入控制台,文件或是 <literal>HttpServletResponse</literal> 的输出流。
-		FreeMarker 并不知道什么是servlet和web;它仅仅是使用模板文件来合并Java对象,
-		之后从它们中间生成输出文本。从这里可知,如何创建一个Web应用程序都随你的习惯来。</para>
-
-        <para>但是,你可能想在已经存在的Web应用框架中使用FreeMarker。
-		许多框架都是基于"Model 2"架构的,JSP页面来控制显示。
-		如果你使用了这样的框架(比如<link 
-		xlink:href="http://jakarta.apache.org/struts">Apache Struts</link>),
-		那么可以继续阅读本文。对于其他框架请参考它们的文档。</para>
-
-        <section xml:id="pgui_misc_servlet_model2">
-          <title>在"Model 2"中使用FreeMarker</title>
-
-          <para>许多框架依照HTTP请求转发给用户自定义的"action"类,
-		  将数据作为属性放在 <literal>ServletContext</literal>,
-		  <literal>HttpSession</literal> 和 <literal>HttpServletRequest</literal> 对象中,
-		  之后请求被框架派发到一个JSP页面中(视图层),使用属性传递过来的数据来生成HTML页面,
-		  这样的策略通常就是所指的Model 2模型。</para>
-
-          <mediaobject>
-            <imageobject>
-              <imagedata fileref="figures/model2sketch.png"/>
-            </imageobject>
-          </mediaobject>
-
-          <para>使用这样的框架,你就可以非常容易地用FTL文件来代替JSP文件。
-		  但是,因为你的Servlet容器(Web应用程序服务器),不像JSP文件,
-		  它可能并不知道如何处理FTL文件,那么就需要对Web应用程序进行一些额外的配置:</para>
-
-          <orderedlist>
-            <listitem>
-              <para>复制 <literal>freemarker.jar</literal> 
-			  (从FreeMarker发布包的<literal>lib</literal>目录中)
-              到Web应用程序的 <literal>WEB-INF/lib</literal> 目录下。</para>
-            </listitem>
-
-            <listitem>
-              <para>将下面的部分添加到Web应用程序的 
-			  <literal>WEB-INF/web.xml</literal> 文件中
-			  (调整部分内容是否需要):</para>
-            </listitem>
-          </orderedlist>
-
-          <programlisting role="unspecified">&lt;servlet&gt;
-  &lt;servlet-name&gt;freemarker&lt;/servlet-name&gt;
-  &lt;servlet-class&gt;<emphasis>freemarker.ext.servlet.FreemarkerServlet</emphasis>&lt;/servlet-class&gt;
-    
-  &lt;!-- FreemarkerServlet settings: --&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;TemplatePath&lt;/param-name&gt;
-    &lt;param-value&gt;/&lt;/param-value&gt;
-  &lt;/init-param&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;NoCache&lt;/param-name&gt;
-    &lt;param-value&gt;true&lt;/param-value&gt;
-  &lt;/init-param&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;ContentType&lt;/param-name&gt;
-    &lt;param-value&gt;text/html; charset=UTF-8&lt;/param-value&gt; &lt;!-- Forces UTF-8 output encoding! --&gt;
-  &lt;/init-param&gt;
-    
-  &lt;!-- FreeMarker settings: --&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;incompatible_improvements&lt;/param-name&gt;
-    &lt;param-value&gt;2.3.22&lt;/param-value&gt;
-    &lt;!-- Recommended to set to a high value. For the details, see the Java API docs of
-         freemarker.template.Configuration#Configuration(Version). --&gt;
-  &lt;/init-param&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;template_exception_handler&lt;/param-name&gt;
-    &lt;!-- Use "html_debug" instead during development! --&gt;
-    &lt;param-value&gt;rethrow&lt;/param-value&gt;
-  &lt;/init-param&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;template_update_delay&lt;/param-name&gt;
-    &lt;!-- ATTENTION, 0 is for development only! Use higher value otherwise. --&gt;
-    &lt;param-value&gt;0&lt;/param-value&gt;
-  &lt;/init-param&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;default_encoding&lt;/param-name&gt;
-    &lt;!-- The encoding of the template files. --&gt;
-    &lt;param-value&gt;UTF-8&lt;/param-value&gt;
-  &lt;/init-param&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;locale&lt;/param-name&gt;
-    &lt;!-- Influences number and date/time formatting, etc. --&gt;
-    &lt;param-value&gt;en_US&lt;/param-value&gt;
-  &lt;/init-param&gt;
-  &lt;init-param&gt;
-    &lt;param-name&gt;number_format&lt;/param-name&gt;
-    &lt;param-value&gt;0.##########&lt;/param-value&gt;
-  &lt;/init-param&gt;
-
-  &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
-&lt;/servlet&gt;
-
-&lt;servlet-mapping&gt;
-  &lt;servlet-name&gt;freemarker&lt;/servlet-name&gt;
-  &lt;url-pattern&gt;<emphasis>*.ftl</emphasis>&lt;/url-pattern&gt;
-&lt;/servlet-mapping&gt;
-
-<replaceable>...</replaceable>
-
-&lt;!--
-  Prevent the visiting of MVC Views from outside the servlet container.
-  RequestDispatcher.forward/include should, and will still work.
-  Removing this may open security holes!
---&gt;
-&lt;security-constraint&gt;
-  &lt;web-resource-collection&gt;
-    &lt;web-resource-name&gt;FreeMarker MVC Views&lt;/web-resource-name&gt;
-    &lt;url-pattern&gt;*.ftl&lt;/url-pattern&gt;
-  &lt;/web-resource-collection&gt;
-  &lt;auth-constraint&gt;
-    &lt;!-- Nobody is allowed to visit these directly. --&gt;
-  &lt;/auth-constraint&gt;
-&lt;/security-constraint&gt;</programlisting>
-
-          <para>在这之后,你可以像使用JSP(<literal>*.jsp</literal>)
-		  文件那样使用FTL文件(<literal>*.ftl</literal>)了。
-		  (当然你可以选择除 <literal>ftl</literal> 之外的扩展名;这只是惯例)</para>
-
-          <note>
-            <para>它是怎么工作的?让我们先来看看JSP是怎么工作的。
-			许多servlet容器处理JSP时使用一个映射为 <literal>*.jsp</literal> 
-			的servlet请求URL格式。这样servlet就会接收所有URL是以 
-			<literal>.jsp</literal> 结尾的请求,查找请求URL地址中的JSP文件,
-			内部编译后生成 <literal>Servlet</literal>,然后调用生成好的serlvet来生成页面。
-			这里为URL类型是 <literal>*.ftl</literal> 映射的 
-			<literal>FreemarkerServlet</literal> 也是相同功能,只是FTL文件不会编译成 
-			<literal>Servlet</literal>,而是给 <literal>Template</literal> 对象,
-			之后 <literal>Template</literal> 对象的 <literal>process</literal> 
-			方法就会被调用来生成页面。</para>
-          </note>
-
-          <para><anchor xml:id="topic.servlet.scopeAttr"/>比如,代替这个JSP页面
-		  (注意它使用了Struts标签库来保存设计,而不是嵌入可怕的Java代码):</para>
-
-          <programlisting role="template">&lt;%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %&gt;
-&lt;%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %&gt;
-
-&lt;html&gt;
-&lt;head&gt;&lt;title&gt;Acmee Products International&lt;/title&gt;
-&lt;body&gt;
-  &lt;h1&gt;Hello &lt;bean:write name="user"/&gt;!&lt;/h1&gt;
-  &lt;p&gt;These are our latest offers:
-  &lt;ul&gt;
-    &lt;logic:iterate name="latestProducts" id="prod"&gt;
-      &lt;li&gt;&lt;bean:write name="prod" property="name"/&gt;
-        for &lt;bean:write name="prod" property="price"/&gt; Credits.
-    &lt;/logic:iterate&gt;
-  &lt;/ul&gt;
-&lt;/body&gt;
-&lt;/html&gt;</programlisting>
-
-          <para>你可以使用这个FTL文件(使用 <literal>ftl</literal> 
-		  扩展名而不是 <literal>jsp</literal>):</para>
-
-          <programlisting role="template">&lt;html&gt;
-&lt;head&gt;&lt;title&gt;Acmee Products International&lt;/title&gt;
-&lt;body&gt;
-  &lt;h1&gt;Hello ${user}!&lt;/h1&gt;
-  &lt;p&gt;These are our latest offers:
-  &lt;ul&gt;
-    &lt;#list latestProducts as prod&gt;
-      &lt;li&gt;${prod.name} for ${prod.price} Credits.
-    &lt;/#list&gt;
-  &lt;/ul&gt;
-&lt;/body&gt;
-&lt;/html&gt;</programlisting>
-
-          <warning>
-            <para>在 FreeMarker 中,<literal>&lt;html:form
-            action="/query"&gt;<replaceable>...</replaceable>&lt;/html:form&gt;</literal> 
-			仅仅被视为是静态文本,所以它会按照原本输出出来了,就像其他XML或HTML标记一样。
-			JSP标签也仅仅是FreeMarker的指令,没有什么特殊之处,所以你可以 
-			<emphasis>使用FreeMarker语法</emphasis> 形式来调用它们,而不是JSP语法:
-			<literal>&lt;@html.form
-            action="/query"&gt;<replaceable>...</replaceable>&lt;/@html.form&gt;</literal>。
-			注意在FreeMarker语法中 <emphasis>不能像JSP那样在参数中使用
-			<literal>${<replaceable>...</replaceable>}</literal></emphasis>,
-			而且<emphasis>不能给参数值加引号</emphasis>。
-			所以这样是<emphasis>错误的</emphasis>:</para>
-
-            <programlisting role="template">&lt;#-- WRONG: --&gt;
-&lt;@my.jspTag color="${aVariable}" name="aStringLiteral"
-            width="100" height=${a+b} /&gt;</programlisting>
-
-            <para>但下面这样是正确的:</para>
-
-            <programlisting role="template">&lt;#-- Good: --&gt;
-&lt;@my.jspTag color=aVariable name="aStringLiteral"
-            width=100 height=a+b /&gt;</programlisting>
-          </warning>
-
-          <para>在这两个模板中,当你要引用 <literal>user</literal> 和 
-		  <literal>latestProduct</literal> 时,首先它会尝试去查找已经在模板中创建的同名变量
-		  (比如 <literal>prod</literal>;如果你使用JSP:这是一个page范围内的属性)。
-		  如果那样做不行,它会尝试在 <literal>HttpServletRequest</literal> 对象中查找那个名字的属性,
-		  如果没有找到就在 <literal>HttpSession</literal> 中找,如果还没有找到那就在 
-		  <literal>ServletContext</literal> 中找。FTL按这种情况工作是因为 
-		  <literal>FreemarkerServlet</literal> 创建数据模型由上面提到的3个对象中的属性而来。
-		  那也就是说,这种情况下根哈希表root不是 <literal>java.util.Map</literal> 
-		  (正如本手册中的一些例子那样),而是 
-		  <literal>ServletContext</literal>+<literal>HttpSession</literal>+<literal>HttpServletRequest</literal>
-		  ;FreeMarker 在处理数据模型类型的时候非常灵活。所以如果你想将变量 
-		  <literal>"name"</literal> 放到数据模型中,那么你可以调用 
-		  <literal>servletRequest.setAttribute("name", "Fred")</literal>;这是模型2的逻辑,
-		  而 FreeMarker 将会适应它。</para>
-
-          <para><literal>FreemarkerServlet</literal> 也会在数据模型中放置3个哈希表,
-		  这样你就可以直接访问3个对象中的属性了。这些哈希表变量是:<literal>Request</literal>,
-		  <literal>Session</literal>,<literal>Application</literal>
-		  (和<literal>ServletContext</literal>对应)。它还会暴露另外一个名为 
-		  <literal>RequestParameters</literal> 的哈希表,这个哈希表提供访问HTTP请求中的参数。</para>
-
-          <para><literal>FreemarkerServlet</literal> 也有很多初始参数。
-		  它可以被设置从任意路径来加载模板,从类路径下,或相对于Web应用程序的目录。
-		  你可以设置模板使用的字符集。你还可以设置想使用的对象包装器等等。</para>
-
-          <para>通过子类别,<literal>FreemarkerServlet</literal> 易于定制特殊需要。
-		  那就是说,如果你需要对所有模板添加一个额外的可用变量,使用servlet的子类,
-		  覆盖 <literal>preTemplateProcess()</literal> 方法,在模板被执行前,
-		  将你需要的额外数据放到模型中。或者在servlet的子类中,在 
-		  <literal>Configuration</literal> 中设置这些全局的变量作为 
-		  <link linkend="pgui_config_sharedvariables">共享变量</link>。</para>
-
-          <para>要获取更多信息,可以阅读该类的Java API文档。</para>
-        </section>
-
-        <section xml:id="pgui_misc_servlet_include">
-          <title>包含其它Web应用程序资源中的内容</title>
-
-          <indexterm>
-            <primary>include</primary>
-
-            <secondary>servlet</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>include</primary>
-
-            <secondary>JSP</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>servlet</primary>
-
-            <secondary>include</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>JSP</primary>
-
-            <secondary>include</secondary>
-          </indexterm>
-
-          <para>你可以使用由 <literal>FreemarkerServlet</literal> (2.3.15版本之后)
-		  提供的客户化标签<literal>&lt;@include_page path="..."/&gt;</literal>
-		  来包含另一个Web应用资源的内容到输出内容中;这对于整合JSP页面
-		  (在同一Web服务器中生活在FreeMarker模板旁边)
-		  的输出到FreeMarker模板的输出中非常有用。使用:</para>
-
-          <programlisting role="template">&lt;@include_page path="path/to/some.jsp"/&gt;</programlisting>
-
-          <para>和在JSP中使用该标签是相同的:</para>
-
-          <programlisting role="template">&lt;jsp:include page="path/to/some.jsp"&gt;</programlisting>
-
-          <note>
-            <para><literal>&lt;@include_page ...&gt;</literal> 不能和 
-            <literal>&lt;#include ...&gt;</literal>搞混,
-			后者是为了包含FreeMarker模板而不会牵涉到Servlet容器。
-			使用 <literal>&lt;#include ...&gt;</literal> 包含的模板和包含它的模板共享模板处理状态,
-			比如数据模型和模板语言变量,而 <literal>&lt;@include_page ...&gt;</literal> 
-			开始一个独立的HTTP请求处理。</para>
-          </note>
-
-          <note>
-            <para>一些Web应用框架为此提供它们自己的解决方案,
-			这种情况下你就可以使用它们来替代。
-			而一些Web应用框架不使用 <literal>FreemarkerServlet</literal>,
-			所以 <literal>include_page</literal> 是不可用的。</para>
-          </note>
-
-          <para>路径可以是相对的,也可以是绝对的。相对路径被解释成相对于当前HTTP请求
-		  (一个可以触发模板执行的请求)的URL,而绝对路径在当前的servlet上下文
-		  (当前的Web应用)中是绝对的。你不能从当前Web应用的外部包含页面。
-		  注意你可以包含任意页面,而不仅仅是JSP页面;
-		  我们仅仅使用以 <literal>.jsp</literal> 结尾的页面作为说明。</para>
-
-          <para>除了参数 <literal>path</literal> 之外,你也可以用布尔值
-		  (当不指定时默认是true)指定一个名为 <literal>inherit_params</literal> 
-		  可选的参数来指定被包含的页面对当前的请求是否可见HTTP请求中的参数。</para>
-
-          <para>最后,你可以指定一个名为 <literal>params</literal> 的可选参数,
-		  来指定被包含页面可见的新请求参数。如果也传递继承的参数,
-		  那么指定参数的值将会得到前缀名称相同的继承参数的值。<literal>params</literal> 
-		  的值必须是一个哈希表类型,它其中的每个值可以是字符串,
-		  或者是字符串序列(如果你需要多值参数)。这里给出一个完整的示例:</para>
-
-          <programlisting role="template">&lt;@include_page path="path/to/some.jsp" inherit_params=true params={"foo": "99", "bar": ["a", "b"]}/&gt;</programlisting>
-
-          <para>这会包含 <literal>path/to/some.jsp</literal> 页面,
-		  传递它的所有的当前请求的参数,除了"foo"和"bar",
-		  这两个会被分别设置为"99"和多值序列"a","b"。
-		  如果原来请求中已经有这些参数的值了,那么新值会添加到原来存在的值中。
-		  那就是说,如果"foo"有值"111"和"123",那么现在它会有"99","111","123"。</para>
-
-          <para><phrase role="forProgrammers">事实上使用 <literal>params</literal> 
-		  给参数传递非字符串值是可能的。这样的一个值首先会被转换为适合的Java对象
-		  (数字,布尔值,日期等),之后调用它们Java对象的 <literal>toString()</literal> 
-		  方法来得到字符串值。最好不要依赖这种机制,作为替代,
-		  明确参数值在模板级别不能转换成字符串类型之后,
-		  在使用到它的地方可以使用内建函数 <literal>?string</literal> 
-		  和 <literal>?c</literal>。</phrase></para>
-        </section>
-
-        <section>
-          <title>在FTL中使用自定义JSP标签</title>
-
-          <indexterm>
-            <primary>JSP</primary>
-
-            <secondary>taglib</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>custom tags</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>taglib</primary>
-          </indexterm>
-
-          <para><literal>FreemarkerServlet</literal> 将一个哈希表类型的 
-		  <literal>JspTaglibs</literal> 放到数据模型中,就可以使用它来访问JSP标签库了。
-		  自定义JSP标签库将被视为普通用户自定义指令来访问,自定义EL函数
-		  (从 FreeMarker 2.3.22 版本开始)视为方法。例如,这个JSP文件:</para>
-
-          <programlisting role="template">&lt;%@ page contentType="text/html;charset=ISO-8859-2" language="java"%&gt;
-&lt;%@ taglib prefix="e" uri="/WEB-INF/example.tld" %&gt;
-&lt;%@ taglib prefix="oe" uri="/WEB-INF/other-example.tld" %&gt;
-&lt;%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %&gt;
-&lt;%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %&gt;
-
-&lt;%-- Custom JSP tags and functions: --%&gt;
-
-&lt;e:someTag numParam="123" boolParam="true" strParam="Example" anotherParam="${someVar}"&gt;
-  ...
-&lt;/e:someTag&gt;
-
-&lt;oe:otherTag /&gt;
-
-${e:someELFunction(1, 2)}
-
-
-&lt;%-- JSTL: --%&gt;
-
-&lt;c:if test="${foo}"&gt;
-  Do this
-&lt;/c:if&gt;
-
-&lt;c:choose&gt;
-  &lt;c:when test="${x == 1}"&gt;
-      Do this
-  &lt;/c:when&gt;
-  &lt;c:otherwise&gt;
-      Do that
-  &lt;/c:otherwise&gt;
-&lt;/c:choose&gt;
-
-&lt;c:forEach var="person" items="${persons}"&gt;
-  ${person.name}
-&lt;/c:forEach&gt;
-
-${fn:trim(bar)}</programlisting>
-
-          <para>基本一致的FTL是:</para>
-
-          <programlisting role="template">&lt;#assign e=JspTaglibs["/WEB-INF/example.tld"]&gt;
-&lt;#assign oe=JspTaglibs["/WEB-INF/other-example.tld"]&gt;
-
-&lt;#-- Custom JSP tags and functions: --#&gt;
-
-&lt;@e.someTag numParam=123 boolParam=true strParam="Example" anotherParam=someVar&gt;
-  ...
-&lt;/@e.someTag&gt;
-
-&lt;@oe.otherTag /&gt;
-
-${e.someELFunction(1, 2)}
-
-
-&lt;#-- JSTL - Instead, use native FTL constructs: --&gt;
-
-&lt;#if foo&gt;
-  Do this
-&lt;/#if&gt;
-
-&lt;#if x == 1&gt;
-  Do this
-&lt;#else&gt;
-  Do that
-&lt;/#if&gt;
-
-&lt;#list persons as person&gt;
-  ${person.name}
-&lt;/#list&gt;
-
-${bar?trim}</programlisting>
-
-          <note>
-            <para>参数值没有使用引号,而且 
-			<literal>"${<replaceable>...</replaceable>}"</literal> 和JSP中使用的一样。
-			后面会详细解释。</para>
-          </note>
-
-          <note>
-            <para><literal>JspTaglibs</literal> 不是 FreeMarker 的核心特性;
-			它只存在于通过 <literal>FreemarkerServlet</literal> 调用的模板。
-			这是因为JSP 标签/函数 假定一个servlet环境(FreeMarker不会),
-			加上一些Servlet概念被模仿成 <literal>FreemarkerServlet</literal> 
-			创建的特定Freemarker数据模型。很多现代开发框架以纯净的方式使用FreeMarker,
-			而不是通过 <literal>FreemarkerServlet</literal>。</para>
-          </note>
-
-          <para>因为自定义JSP标签是在JSP环境中来书写操作的,它们假设变量
-		  (在JSP中常被指代"beans")被存储在4个范围中:page范围,request范围,
-		  session范围和application范围。FTL没有这样的表示法(4种范围),但是 
-		  <literal>FreemarkerServlet</literal>给自定义标签提供仿真的环境,
-		  这样就可以维持JSP范围中的"beans"和FTL变量之间的对应关系。
-		  对于自定义的JSP标签,请求request,会话session和应用application是和真实JSP相同的:
-		  <literal>javax.servlet.ServletContext</literal>,<literal>HttpSession</literal> 
-		  和 <literal>ServletRequest</literal> 对象中的属性。从FTL的角度来看,
-		  这三种范围都在数据模型中,这点前面已经解释了。page范围和FTL全局变量(参见<link 
-		  linkend="ref.directive.global"><literal>global</literal>指令</link>)是对应的。
-		  那也就是,如果你使用 <literal>global</literal> 指令创建一个变量,通过仿真的JSP环境,
-		  它会作为page范围变量对自定义标签可见。而且,如果一个JSP标签创建了一个新的page范围变量,
-		  那么结果和用 <literal>global</literal> 指令创建的是相同的。
-		  要注意在数据模型中的变量作为page范围的属性对JSP标签是不可见的,尽管它们在全局是可见的,
-		  因为数据模型和请求,会话,应用范围是对应的,而不是page范围。</para>
-
-          <para>在JSP页面中,你可以对所有属性值加引号,这和参数类型是字符串,
-		  布尔值或数字没有关系。但是因为在FTL模板中自定义标签可以被用户自定义FTL指令访问到,
-		  你将不得不在自定义标签中使用FTL语法规则,而不是JSP语法。所以当你指定一个"属性"的值时,
-		  那么在 <literal>=</literal> 的右边是一个 <link 
-		  linkend="dgui_template_exp">FTL 表达式</link>。因此,
-		  <emphasis>你不能对布尔值和数字值的参数加引号</emphasis>
-		  (比如:<literal>&lt;@tiles.insert page="/layout.ftl" flush=true/&gt;</literal>),
-		  否则它们将被解释为字符串值,当FreeMarker试图传递值到期望非字符串值的自定义标记中时,
-		  这就会引起类型不匹配错误。而且还要注意,这很自然,你可以使用任意FTL表达式作为属性的值,
-		  比如变量,计算的结果值等。(比如:<literal>&lt;@tiles.insert page=layoutName
-          flush=foo &amp;&amp; bar/&gt;</literal>)</para>
-
-          <para>Servlet容器运行过程中,因为它实现了自身的轻量级JSP运行时环境,
-		  它用到JSP标签库,而 FreeMarker 并不依赖于JSP支持。这是一个很小但值得注意的地方:
-		  在它们的TLD文件中,开启 FreeMarker 的JSP运行时环境来分发事件到JSP标签库中注册时间监听器,
-		  你应该将下面的内容添加到Web应用下的 <literal>WEB-INF/web.xml</literal> 文件中:</para>
-
-          <programlisting role="unspecified">&lt;listener&gt;
-  &lt;listener-class&gt;freemarker.ext.jsp.EventForwarding&lt;/listener-class&gt;
-&lt;/listener&gt;</programlisting>
-
-          <para>请注意,尽管servlet容器没有本地的JSP支持,你也可以在 FreeMarker 中使用JSP标签库。
-		  只是确保对JSP 1.2版本(或更新)的 <literal>javax.servlet.jsp.*</literal> 
-		  包在Web应用程序中可用就行。如果你的servlet容器只对JSP 1.1支持,
-		  那么你不得不将下面六个类(比如你可以从Tomcat 5.x或Tomcat 4.x的jar包中提取)复制到Web应用的 
-		  <literal>WEB-INF/classes/<replaceable>...</replaceable></literal>目录下:
-		  <literal>javax.servlet.jsp.tagext.IterationTag</literal>,
-          <literal>javax.servlet.jsp.tagext.TryCatchFinally</literal>,
-          <literal>javax.servlet.ServletContextListener</literal>,
-          <literal>javax.servlet.ServletContextAttributeListener</literal>,
-          <literal>javax.servlet.http.HttpSessionAttributeListener</literal>,
-          <literal>javax.servlet.http.HttpSessionListener</literal>。但是要注意,
-		  因为容器只支持JSP 1.1,通常是使用较早的Servlet 2.3之前的版本,
-		  事件监听器可能就不支持,因此JSP 1.2标签库来注册事件监听器会正常工作。</para>
-
-          <para>在撰写本文档时,JSP已经升级到2.1了,许多特性也已经实现了,
-		  除了JSP 2(也就是说JSP自定义标记在JSP语言中<emphasis>实现了</emphasis>)的"标签文件"特性。
-		  标签文件需要被编译成Java类文件,在 FreeMarker 下才会有用。</para>
-
-          <para><literal>JspTaglibs[<replaceable>uri</replaceable>]</literal>
-          会去找到URI指定的TLD,就像JSP的 <literal>@taglib</literal> 指令所做的。
-		  它实现了JSP规范中所描述的TLD发现机制。这里可以阅读更多,但简而言之,
-		  它会在 <literal>WEB-INF/web.xml</literal> <literal>taglib</literal> 元素中,
-		  在 <literal>WEB-INF/**/*.tld</literal> 文件中,还有
-		  <literal>WEB-INF/lib/*.{jar,zip}/META-INF/**/*.tld</literal> 文件中寻找TLD。
-		  此外,当设置了 <literal>FreemarkerServlet</literal> 的初始化参数(从 2.3.22版本开始)
-		  <literal>MetaInfTldSources</literal> 和/或 <literal>ClasspathTlds</literal>,
-		  即便是在WAR结构之外,它也会发现对于类加载器可见的TLD。参考 
-		  <literal>FreemarkerServlet</literal> 的Java API文档来获取更多描述。
-		  它也可以从Java系统属性中来设置,当你想在Eclipse运行配置中来修改而不去修改 
-		  <literal>web.xml</literal>时,就可以随手完成;再强调一点,请参考
-          <literal>FreemarkerServlet</literal> API 文档。
-          <literal>FreemarkerServlet</literal> 也会识别
-          <literal>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</literal>
-          servlet 上下文属性,并且将它中间的配置项添加到
-          <literal>MetaInfTldSources</literal>。</para>
-        </section>
-
-        <section>
-          <title>在JSP页面中嵌入FTL</title>
-
-          <indexterm>
-            <primary>JSP</primary>
-
-            <secondary>taglib</secondary>
-          </indexterm>
-
-          <para>有一个标签库允许你将FTL片段放到JSP页面中。
-		  嵌入的FTL片段可以访问JSP 的4种范围内的属性(Beans)。
-		  你可以在 FreeMarker 发布包中找到一个可用的示例和这个标签库。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_misc_secureenv">
-        <title>为FreeMarker配置安全策略</title>
-
-        <indexterm>
-          <primary>security</primary>
-        </indexterm>
-
-        <para>当 FreeMarker 运行在装有安全管理器的Java虚拟机中时,
-		你不得不再授与一些权限,确保运行良好。最值得注意的是,
-		你需要为对 <literal>freemarker.jar</literal> 
-		的安全策略文件添加这些条目:</para>
-
-        <programlisting role="unspecified">grant codeBase "file:/path/to/freemarker.jar" 
-{
-  permission java.util.PropertyPermission "file.encoding", "read";
-  permission java.util.PropertyPermission "freemarker.*", "read";
-}</programlisting>
-
-        <para>另外,如果从一个目录中加载模板,
-		你还需要给 FreeMarker 授权来从那个目录下读取文件,
-		使用如下的授权:</para>
-
-        <programlisting role="unspecified">grant codeBase "file:/path/to/freemarker.jar" 
-{
-  ...
-  permission java.io.FilePermission "/path/to/templates/-", "read";
-}</programlisting>
-
-        <para>最终,如果你使用默认的模板加载机制,也就是从当前文件夹下加载模板,
-		那么需要指定这些授权内容:(请注意,表达式 <literal>${user.dir}</literal> 
-		将会在运行时被策略解释器处理,几乎它就是一个 FreeMarker 模板)</para>
-
-        <programlisting role="unspecified">
-grant codeBase "file:/path/to/freemarker.jar" 
-{
-  ...
-  permission java.util.PropertyPermission "user.dir", "read";
-  permission java.io.FilePermission "${user.dir}/-", "read";
-}</programlisting>
-
-        <para>很自然地,如果你在Windows下运行,
-		使用两个反斜杠来代替一个斜杠来分隔路径中的目录间隔。</para>
-      </section>
-
-      <section xml:id="pgui_misc_xml_legacy">
-        <title>遗留的XML包装实现</title>
-
-        <note>
-          <para><emphasis>遗留的XML包装已经废弃了。</emphasis>
-          FreeMarker 2.3 已经引入了对新的XML处理模型的支持。要支持它,
-		  新的XML包装包已经引入了,就是 <literal>freemarker.ext.dom</literal>。
-		  对于新用法,我们鼓励你使用。它会在<xref linkend="xgui"/>中来说明。</para>
-        </note>
-
-        <para><literal>freemarker.ext.xml.NodeListModel</literal> 
-		类提供了来包装XML文档展示为结点树模板模型。
-		每个结点列表可以包含零个或多个XML结点
-		(文档类型,元素类型,文本类型,处理指令,注释,实体引用,CDATA段等)。
-		结点列表实现了下面模板的语义模型接口:</para>
-
-        <section>
-          <title>模板标量模型(TemplateScalarModel)</title>
-
-          <para>当使用一个标量时,结点列表将会呈现XML片段,表示其包含的结点。
-		  这使得使用XML到XML转换模板很方便。</para>
-        </section>
-
-        <section>
-          <title>模板集合模型(TemplateCollectionModel)</title>
-
-          <para>当用 <literal>list</literal> 指令来使用一个集合时,
-		  它会简单枚举它的结点。每个结点将会被当作一个新的单一结点组的结点列表返回。</para>
-        </section>
-
-        <section>
-          <title>模板序列模型(TemplateSequenceModel)</title>
-
-          <para>当被用作是序列时,它会返回第i个结点作为一个新的结点列表,
-		  包含单独的被请求的结点。也就是说,要返回 <literal>&lt;book&gt;</literal> 
-		  元素的第三个 <literal>&lt;chapter&gt;</literal> 元素,你可以使用下面的代码
-		  (结点索引是从零开始的):</para>
-
-          <programlisting role="template">&lt;#assign thirdChapter = xmldoc.book.chapter[2]&gt;</programlisting>
-        </section>
-
-        <section>
-          <title>模板哈希表模型(TemplateHashModel)</title>
-
-          <para>当被用作是哈希表时,它基本上是用来遍历子结点。也就是说,
-		  如果你有个名为 <literal>book</literal> 的结点列表,
-		  并包装了一个有很多chapter的元素结点,那么 <literal>book.chapter</literal> 
-		  将会产生一个book元素的所有chapter元素的结点列表。@符号常被用来指代属性:
-		  <literal>book.@title</literal> 产生一个有单独属性的结点列表,
-		  也就是book元素的title属性。</para>
-
-          <para>意识到下面这样的结果是很重要的,比如,如果 <literal>book</literal> 
-		  没有 <literal>chapter</literal>-s,那么 <literal>book.chapter</literal> 
-		  就是一个空序列,所以 <literal>xmldoc.book.chapter??</literal> 就 
-		  <emphasis>不会</emphasis> 是 <literal>false</literal>,它会一直是 
-		  <literal>true</literal>!相似地,
-		  <literal>xmldoc.book.somethingTotallyNonsense??</literal> 
-		  也不会是<literal>false</literal>。为了检查是否发现子结点,可以使用 
-		  <literal>xmldoc.book.chapter?size == 0</literal>。</para>
-
-          <para>哈希表定义了一些"魔力键"。所有的这些键以下划线开头。
-		  最值得注意的是<literal>_text</literal>,可以得到结点的文本内容:
-		  <literal>${book.@title._text}</literal> 将会给模板交出属性的值。
-		  相似地,<literal>_name</literal>将会取得元素或属性的名字。
-		  <literal>*</literal> 或 <literal>_allChildren</literal> 
-		  返回所有结点列表元素中的直接子元素,而 <literal>@*</literal> 
-		  或 <literal>_allAttributes</literal> 返回结点列表中元素的所有属性。
-		  还有很多这样的键;下面给出哈希表键的详细总结:</para>
-
-          <informaltable border="1">
-            <thead>
-              <tr>
-                <th>键名</th>
-
-                <th>结果为</th>
-              </tr>
-            </thead>
-
-            <tbody>
-              <tr>
-                <td><literal>*</literal> 或 <literal>_children</literal></td>
-
-                <td>所有当前结点(非递归)的直接子元素。适用于元素和文档结点。</td>
-              </tr>
-
-              <tr>
-                <td><literal>@*</literal> 或
-                <literal>_attributes</literal></td>
-
-                <td>当前结点的所有属性。仅适用于元素。</td>
-              </tr>
-
-              <tr>
-                <td><literal>@<replaceable>attributeName</replaceable></literal></td>
-
-                <td>当前结点的命名属性。适用于元素,声明和处理指令。
-				在声明中它支持属性 <literal>publicId</literal>,<literal>systemId</literal> 
-				和 <literal>elementName</literal>。在处理指令中,它支持属性 
-				<literal>target</literal> 和 <literal>data</literal>,还有数据中以 
-				<literal>name="value"</literal> 对出现的其他属性名。
-				对于声明和处理指令的属性结点是合成的,因此它们没有父结点。
-				要注意,<literal>@*</literal> 不能在声明或处理指令上进行操作。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_ancestor</literal></td>
-
-                <td>当前结点的所有祖先,直到根元素(递归)。
-				适用于类型和 <literal>_parent</literal> 相同的结点类型。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_ancestorOrSelf</literal></td>
-
-                <td>当前结点和它的所有祖先结点。
-				适用于和 <literal>_parent</literal> 相同的结点类型。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_cname</literal></td>
-
-                <td>当前结点(命名空间URI+本地名称)的标准名称,
-				每个结点(非递归)一个字符串值。适用于元素和属性。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_content</literal></td>
-
-                <td>当前结点的全部内容,包括子元素,文本,
-				实体引用和处理指令(非递归)。适用于元素和文档。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_descendant</literal></td>
-
-                <td>当前结点的所有递归的子孙元素。适用于文档和元素结点。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_descendantOrSelf</literal></td>
-
-                <td>当前结点和它的所有递归的子孙元素。适用于文档和元素结点。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_document</literal></td>
-
-                <td>当前结点所属的所有文档类型。适用于所有除文本的结点。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_doctype</literal></td>
-
-                <td>当前结点的声明。仅仅适用于文档类型结点。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_filterType</literal></td>
-
-                <td>这是一种按类型过滤的模板方法模型。当被调用时,
-				它会产生一个结点列表,仅仅包含它们当前结点,
-				这些结点的类型和传递给它们参数的一种类型相匹配。
-				你应该传递任意数量的字符串给这个方法,
-				其中包含来保持类型的名字。合法的类型名称是:"attribute",
-				"cdata","comment","document","documentType",
-				"element","entity","entityReference",
-				"processingInstruction","text"。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_name</literal></td>
-
-                <td>当前结点的名称。每个结点(非递归)一个字符串值。
-				适用于元素和属性(返回它们的本地名称),实体,
-				处理指令(返回它的目标),声明(返回它的public ID)。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_nsprefix</literal></td>
-
-                <td>当前结点的命名空间前缀,每个结点(非递归)一个字符串值。
-				适用于元素和属性。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_nsuri</literal></td>
-
-                <td>当前结点的命名空间URI,每个结点(非递归)一个字符串值。
-				适用于元素和属性。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_parent</literal></td>
-
-                <td>当前结点的父结点。适用于元素,属性,注释,实体,处理指令。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_qname</literal></td>
-
-                <td>当前结点在 <literal>[namespacePrefix:]localName</literal> 
-				形式的限定名,每个结点(非递归)一个字符串值。适用于元素和属性。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_registerNamespace(prefix, uri)</literal></td>
-
-                <td>注册一个对当前结点列表和从当前结点列表派生出的所有结点列表有指定前缀和URI的XML命名空间。
-				注册之后,你可以使用<literal>nodelist["prefix:localname"]</literal> 或 
-				<literal>nodelist["@prefix:localname"]</literal> 语法来访问元素和属性,
-				它们的名字是命名空间范围内的。
-				注意命名空间的前缀需要不能和当前XML文档它自己使用的前缀相匹配,
-				因为命名空间纯粹是由URI来比较的。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_text</literal></td>
-
-                <td>当前结点的文本内容,每个结点(非递归)一个字符串值。
-				适用于元素,属性,注释,处理指令(返回它的数据)和CDATA段。
-				保留的XML字符('&lt;'和'&amp;')不能被转义。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_type</literal></td>
-
-                <td>返回描述结点类型的结点列表,每个结点包含一个字符串值。
-				可能的结点名称是:合法的结点名称是:"attribute","cdata","comment",
-				"document","documentType","element","entity","entityReference",
-				"processingInstruction","text"。如果结点类型是未知的,就返回"unknown"。</td>
-              </tr>
-
-              <tr>
-                <td><literal>_unique</literal></td>
-
-                <td>当前结点的一个拷贝,仅仅保留每个结点第一次的出现,消除重复。
-				重复可以通过应用对树的向上遍历出现在结点列表中,如<literal>_parent</literal>,
-				<literal>_ancestor</literal>,<literal>_ancestorOrSelf</literal> 和 
-				<literal>_document</literal>,也就是说,<literal>foo._children._parent</literal> 
-				会返回一个结点列表,它包含foo中重复的结点,每个结点会包含出现的次数,
-				和它子结点数目相等。这些情况下,使用 <literal>foo._children._parent._unique</literal> 
-				来消除重复。适用于所有结点类型。</td>
-              </tr>
-
-              <tr>
-                <td>其它键</td>
-
-                <td>当前结点的子元素的名称和键相匹配。这允许以 
-				<literal>book.chapter.title</literal> 这种风格语法进行方便的子元素遍历。
-				请注意,在技术上 <literal>nodeset.childname</literal> 和 
-				<literal>nodeset("childname")</literal> 相同,但是两者写法都很短,
-				处理也很迅速。适用于文档和元素结点。</td>
-              </tr>
-            </tbody>
-          </informaltable>
-        </section>
-
-        <section>
-          <title>模板方法模型(TemplateMethodModel)</title>
-
-          <para>当被用作方法模型,它返回一个结点列表,
-		  这个列表是处理结点列表中当前内容的XPath表达式的结果。
-		  为了使这种特性能够工作,你必须将 <literal>Jaxen</literal> 
-		  类库放到类路径下。比如:</para>
-
-          <programlisting role="template">&lt;#assign firstChapter=xmldoc("//chapter[first()]")&gt;</programlisting>
-        </section>
-
-        <section>
-          <title>命名空间处理</title>
-
-          <para>为了遍历有命名空间范围内名称的子元素这个目的,
-		  你可以使用结点列表注册命名空间前缀。
-		  你可以在Java代码中来做,调用:</para>
-
-          <programlisting role="unspecified">public void registerNamespace(String prefix, String uri);</programlisting>
-
-          <para>方法,或者在模板中使用</para>
-
-          <programlisting role="template">${<replaceable>nodelist</replaceable>._registerNamespace(<replaceable>prefix</replaceable>, <replaceable>uri</replaceable>)}</programlisting>
-
-          <para>语法。从那里开始,
-		  你可以在命名空间通过特定的URI来标记引用子元素,用这种语法</para>
-
-          <programlisting role="metaTemplate"><literal><replaceable>nodelist</replaceable>["<replaceable>prefix</replaceable>:<replaceable>localName</replaceable>"]</literal></programlisting>
-
-          <para>和</para>
-
-          <programlisting role="metaTemplate"><literal><replaceable>nodelist</replaceable>["@<replaceable>prefix</replaceable>:<replaceable>localName</replaceable>"]</literal></programlisting>
-
-          <para>和在 XPath 表达式中使用这些命名空间前缀一样。
-		  命名空间使用一个结点列表来注册并传播到所有结点列表,
-		  这些结点列表来自于原来的结点列表。要注意命名空间只可使用URI来进行匹配,
-		  所以你可以在你的模板中安全地使用命名空间的前缀,这和在实际XML中的不同,
-		  在模板和XML文档中,一个前缀只是一个对URI的本地别名。</para>
-        </section>
-      </section>
-
-      <section xml:id="pgui_misc_ant">
-        <title>和Ant一起使用FreeMarker</title>
-
-        <indexterm>
-          <primary>ant task</primary>
-        </indexterm>
-
-        <para>我们现在知道有两种"FreeMarker Ant tasks":</para>
-
-        <itemizedlist>
-          <listitem>
-            <para><literal>FreemarkerXmlTask</literal>:它来自于FreeMarker的发布包,
-			打包到 <literal>freemarker.jar</literal> 中。
-			这是使用FreeMarker模板转换XML文档的轻量级的,易于使用的Ant任务。
-			它的入口源文件(输入文件)是XML文件,和生成的输出文件对应,
-			这是通过单独模板实现的。也就是说,对于每个XML文件,
-			模板会被执行(在数据模型中的XML文档),
-			模板的输出会被写入到一个和原XML文件名相似名称的文件中。
-			因此,模板文件扮演了一个和XSLT样式表相似的角色,但它是FTL,而不是XSLT。</para>
-          </listitem>
-
-          <listitem>
-            <para><indexterm>
-                <primary>command-line</primary>
-              </indexterm>FMPP:这是一个重量级的,以很少的XML为中心,
-			  第三方Ant任务(和独立的命令行工具)。
-			  它主要的目的是用作为模板文件的源文件(输入文件)生成它们自己对应的输出文件,
-			  但它也对以XML为源文件的 <literal>FreemarkerXmlTask</literal> 进行支持。
-			  而且,相比于<literal>FreemarkerXmlTask</literal>,它还有额外的特性。
-			  那么它的缺点是什么?它太复杂太一般化了,不容易掌握和使用。</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>这一部分介绍了 <literal>FreemarkerXmlTask</literal>,
-		要了解FMPP更多的信息,可以访问它的主页:<link
-        xlink:href="http://fmpp.sourceforge.net/">http://fmpp.sourceforge.net/</link>。</para>
-
-        <para>为了使用 <literal>FreemarkerXmlTask</literal>,
-		首先必须在你的Ant构建文件中定义 
-		<literal>freemarker.ext.ant.FreemarkerXmlTask</literal>,然后调用任务。
-		假设你想使用假定的"xml2html.ftl"模板转换一些XML文档到HTML,
-		XML文档在目录"xml"中而HTML文档生成到目录"html"中,你应该这样来写:</para>
-
-        <programlisting role="unspecified">&lt;taskdef name="freemarker" classname="freemarker.ext.ant.FreemarkerXmlTask"&gt;
-  &lt;classpath&gt;
-    &lt;pathelement location="freemarker.jar" /&gt;
-  &lt;/classpath&gt;
-&lt;/taskdef&gt;
-&lt;mkdir dir="html" /&gt;
-&lt;freemarker basedir="xml" destdir="html" includes="**/*.xml" template="xml2html.ftl" /&gt;</programlisting>
-
-        <para>这个任务将会对每个XML文档调用模板。每个文档将会被解析成DOM树,
-		然后包装成FreeMarker结点变量。当模板开始执行时,
-		特殊变量 <literal>.node</literal> 被设置成XML文档结点的根root。</para>
-
-        <para>请注意,如果你正使用遗留的(FreeMarker 2.2.x 和以前版本)XML适配器实现,
-		也同样可以进行,而且XML树的根结点被放置在数据模型中,
-		作为变量 <literal>document</literal>。它包含了遗留的 
-		<literal>freemarker.ext.xml.NodeListModel</literal> 类的实例。</para>
-
-        <para>请注意,所有通过构建文件定义的属性将会作为名为"properties"的哈希表模型来用。
-		一些其他方法也会可用;对模板中什么样的可用变量的详细描述,
-		还有什么样的属性可以被任务接受,参见 
-		<literal>freemarker.ext.ant.FreemarkerXmlTask</literal> 的JavaDoc文档。</para>
-      </section>
-
-      <section xml:id="pgui_misc_jythonwrapper">
-        <title>Jython包装器</title>
-
-        <indexterm>
-          <primary>wrapping</primary>
-
-          <secondary>jython</secondary>
-        </indexterm>
-
-        <indexterm>
-          <primary>jython</primary>
-
-          <secondary>wrapping</secondary>
-        </indexterm>
-
-        <para><literal>freemarker.ext.jython</literal> 
-		包包含了启用任意Jython对象的模型,
-		并被用作是<literal>TemplateModel</literal>。在一个基础的示例中,
-		你可以使用如下调用:</para>
-
-        <programlisting role="unspecified">public TemplateModel wrap(Object obj);</programlisting>
-
-        <para><literal>freemarker.ext.jython.JythonWrapper</literal> 类的方法。
-		这个方法会包装传递的对象,包装成合适的 <literal>TemplateModel</literal>。
-		下面是一个对返回对象包装器的属性的总结。为了下面的讨论,
-		我们假设在模板模型根中,对对象 <literal>obj</literal> 调用 
-		<literal>JythonWrapper</literal> 后模型名为 <literal>model</literal>。</para>
-
-        <section>
-          <title>模板哈希表模型功能(TemplateHashModel functionality)</title>
-
-          <para><literal>PyDictionary</literal> 和
-          <literal>PyStringMap</literal> 将会被包装成一个哈希表模型。
-		  键的查找映射到 <literal>__finditem__</literal> 
-		  方法;如果一个项没有被找到,
-		  那么就返回一个为 <literal>None</literal> 的模型。</para>
-        </section>
-
-        <section>
-          <title>模板标量模型功能(TemplateScalarModel functionality)</title>
-
-          <para>每一个python对象会实现 
-		  <literal>TemplateScalarModel</literal> 接口,
-		  其中的 <literal>getAsString()</literal> 
-		  方法会委派给 <literal>toString()</literal> 方法。</para>
-        </section>
-
-        <section>
-          <title>模板布尔值模型功能(TemplateBooleanModel functionality)</title>
-
-          <para>每一个python对象会实现 
-		  <literal>TemplateBooleanModel</literal> 接口,
-		  其中的 <literal>getAsBoolean()</literal> 方法会指派给 
-		  <literal>__nonzero__()</literal> 方法,
-		  符合Python语义的true/false。</para>
-        </section>
-
-        <section>
-          <title>模板数字模型功能(TemplateNumberModel functionality)</title>
-
-          <para>对<literal>PyInteger</literal>,<literal>PyLong</literal> 和 
-		  <literal>PyFloat</literal> 对象的模型包装器实现了 
-		  <literal>TemplateNumberModel</literal> 接口,其中的 
-		  <literal>getAsNumber()</literal> 方法返回 
-		  <literal>__tojava__(java.lang.Number.class)</literal>。</para>
-        </section>
-
-        <section>
-          <title>模板序列模型功能(TemplateSequenceModel functionality)</title>
-
-          <para>对所有扩展了 <literal>PySequence</literal> 的类的模型包装器会实现 
-		  <literal>TemplateSequenceModel</literal> 接口,
-		  因此它们中的元素可以通过使用 <literal>model[i]</literal> 语法形式的序列来访问,
-		  这会指派给<literal>__finditem__(i)</literal>。你也可以使用内建函数 
-		  <literal>model?size</literal> 查询数组的长度或者list的大小,
-		  它会指派给 <literal>__len__()</literal>。</para>
-        </section>
-      </section>
-    </chapter>
-  </part>
-
-  <part xml:id="ref">
-    <title>模板语言参考 </title>
-
-    <chapter xml:id="ref_builtins">
-      <title>内建函数参考</title>
-
-      <indexterm>
-        <primary>built-in</primary>
-      </indexterm>
-
-      <section xml:id="ref_builtins_alphaidx">
-        <title>字母顺序索引</title>
-
-        <note>
-          <para>在 FreeMarker 2.3.23 中,指令名可以使用驼峰样式来代替蛇形样式,
-		  比如 <literal>startsWith</literal> 代替 <literal>starts_with</literal>。
-		  但是要知道,在相同模版内,FreeMarker 会强制对模板语言部分的所有标识符使用驼峰样式
-		  (用户自定义名称不会受影响)。</para>
-        </note>
-
-        <indexterm>
-          <primary>built-in</primary>
-        </indexterm>
-
-        <itemizedlist spacing="compact">
-          <listitem>
-            <para><link linkend="ref_builtin_abs">abs</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_ancestors">ancestors</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_buitin_api_and_has_api">api</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_boolean">boolean</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_numType">byte</link></para>
-          </listitem>
-
-          <listitem>
-            <para>c <link linkend="ref_builtin_c">for strings</link>, <link
-            linkend="ref_builtin_c_boolean">for booleans</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_cap_first">cap_first</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_capitalize">capitalize</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_rounding">ceiling</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_children">children</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_chop_linebreak">chop_linebreak</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_chunk">chunk</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_contains">contains</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_counter">counter</link></para>
-          </listitem>
-
-          <listitem>
-            <para>date <link linkend="ref_builtin_date_datetype">for
-            dates</link>, <link linkend="ref_builtin_string_date">for
-            strings</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_date_if_unknown">date_if_unknown</link></para>
-          </listitem>
-
-          <listitem>
-            <para>datetime <link linkend="ref_builtin_date_datetype">for
-            dates</link>, <link linkend="ref_builtin_string_date">for
-            strings</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_date_if_unknown">datetime_if_unknown</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_numType">double</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_ends_with">ends_with</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_ensure_ends_with">ensure_ends_with</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_ensure_starts_with">ensure_starts_with</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_eval">eval</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_first">first</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_rounding">floor</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_groups">groups</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_numType">float</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_buitin_api_and_has_api">has_api</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_has_content">has_content</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_has_next">has_next</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_html">html</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_index">index</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_index_of">index_of</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_numType">int</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_interpret">interpret</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_item_cycle">item_cycle</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_item_parity">item_parity</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_item_parity_cap">item_parity_cap</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_is_even_item">is_even_item</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_first">is_first</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_is_infinite">is_infinite</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_is_last">is_last</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_is_nan">is_nan</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_is_odd_item">is_odd_item</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_isType">is_<replaceable>type</replaceable></link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_date_iso">iso,
-            iso_...</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_j_string">j_string</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_join">join</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_js_string">js_string</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_keep_after">keep_after</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_keep_after_last">keep_after_last</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_keep_before">keep_before</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_keep_before_last">keep_before_last</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_keys">keys</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_last">last</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_last_index_of">last_index_of</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_left_pad">left_pad</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_length">length</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_numType">long</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_lower_abc">lower_abc</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_lower_case">lower_case</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_matches">matches</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_namespace">namespace</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_new">new</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_node_namespace">node_namespace</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_node_name">node_name</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_node_type">node_type</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_number">number</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_numToDate">number_to_date,
-            number_to_datetime, number_to_time</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_parent">parent</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_replace">replace</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_remove_beginning">remove_beginning</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_remove_ending">remove_ending</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_reverse">reverse</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_right_pad">right_pad</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_rounding">round</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_root">root</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_rtf">rtf</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_numType">short</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_size">size</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_sort">sort</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_seq_contains">seq_contains</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_seq_index_of">seq_index_of</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_seq_last_index_of">seq_last_index_of</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_sort_by">sort_by</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_split">split</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_starts_with">starts_with</link></para>
-          </listitem>
-
-          <listitem>
-            <para>string: <link linkend="ref_builtin_string_for_string">for
-            strings</link>, <link linkend="ref_builtin_string_for_number">for
-            numbers</link>, <link linkend="ref_builtin_string_for_boolean">for
-            booleans</link>, <link linkend="ref_builtin_string_for_date">for
-            date/time/date-time</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_substring">substring</link>
-            (deprecated)</para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_switch">switch</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_then">then</link></para>
-          </listitem>
-
-          <listitem>
-            <para>time <link linkend="ref_builtin_date_datetype">for
-            date/time/date-time</link>, <link
-            linkend="ref_builtin_string_date">for strings</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_date_if_unknown">time_if_unknown</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_trim">trim</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_uncap_first">uncap_first</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_upper_abc">upper_abc</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_upper_case">upper_case</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_url">url</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_values">values</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link
-            linkend="ref_builtin_word_list">word_list</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_xhtml">xhtml</link></para>
-          </listitem>
-
-          <listitem>
-            <para><link linkend="ref_builtin_xml">xml</link></para>
-          </listitem>
-        </itemizedlist>
-
-        <para>点击 <link
-        linkend="ref_builtins">这里</link> 参考按照表达式左侧值类型分类的内建函数。</para>
-
-        <para>如果在这里没有发现模板中的内建函数,那么可能会在这里找到:<xref
-        linkend="ref_deprecated"/></para>
-      </section>
-
-      <section xml:id="ref_builtins_string">
-        <title>字符串内建函数</title>
-
-        <indexterm>
-          <primary>string</primary>
-
-          <secondary>built-ins</secondary>
-        </indexterm>
-
-        <para>这些内建函数作用于表达式左侧的字符串值。
-		如果左侧值是数字或日期/时间/日期-时间或布尔类型(从 2.3.20 版本开始),
-		根据当前的number-, date/time/date-time- 和 boolean-format设置,
-		那么它会自动被转成字符串值(当使用<literal>${<replaceable>...</replaceable>}</literal>
-		插入这些值时,应用的都是一样的格式程序)。</para>
-
-        <section xml:id="ref_builtin_boolean">
-          <title>boolean</title>
-
-          <indexterm>
-            <primary>type-casting</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>converting between types</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>boolean built-in</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>string to boolean</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>converting string to boolean</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>parse string as boolean</primary>
-          </indexterm>
-
-          <para>字符串转为布尔值。字符串必须是
-          <literal>true</literal> 或 <literal>false</literal>
-		  (大小写敏感!),或者必须是由 <literal>boolean_format</literal> 
-		  设置的特定格式。</para>
-
-          <para>如果字符串不是适当的格式,那么当访问该内建函数时,
-		  就会发成错误终止模板处理。</para>
-        </section>
-
-        <section xml:id="ref_builtin_cap_first">
-          <title>cap_first</title>
-
-          <indexterm>
-            <primary>cap_first built-in</primary>
-          </indexterm>
-
-          <para>字符串中的首单词的首字母大写。
-		  关于"单词"的准确意义,可以参考 <link
-          linkend="ref_builtin_word_list">word_list 内建函数</link>。
-          例如:</para>
-
-          <programlisting role="template">${"  green mouse"?cap_first}
-${"GreEN mouse"?cap_first}
-${"- green mouse"?cap_first}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  Green mouse
-GreEN mouse
-- green mouse</programlisting>
-
-          <para>In the case of <literal>"- green mouse"</literal>, the first
-          word is the <literal>-</literal>.</para>
-        </section>
-
-        <section xml:id="ref_builtin_capitalize">
-          <title>capitalize</title>
-
-          <indexterm>
-            <primary>capitalize built-in</primary>
-          </indexterm>
-
-          <para>字符串中所有单词的首字母大写。
-		  关于"单词"的准确意义,可以参考 <link 
-		  linkend="ref_builtin_word_list">word_list 内建函数</link>。例如:</para>
-
-          <programlisting role="template">${"  green  mouse"?capitalize}
-${"GreEN mouse"?capitalize}</programlisting>
-
-          <para>将会输出:</para>
-
-          <programlisting role="output">  Green Mouse
-Green Mouse</programlisting>
-        </section>
-
-        <section xml:id="ref_builtin_chop_linebreak">
-          <title>chop_linebreak</title>
-
-          <indexterm>
-            <primary>chop_linebreak built-in</primary>
-          </indexterm>
-
-          <para>在末尾没有 <link
-          linkend="gloss.lineBreak">换行符</link> 的字符串,
-		  那么可以换行,否则不改变字符串。</para>
-        </section>
-
-        <section xml:id="ref_builtin_contains">
-          <title>contains</title>
-
-          <indexterm>
-            <primary>contains built-in</primary>
-          </indexterm>
-
-          <note>
-            <para>这个内建函数从 FreeMarker 2.3.1 版本开始可用。
-			在2.3版本中是没有的。</para>
-          </note>
-
-          <para>如果函数中的参数指定的子串出现在源字符串中,
-		  那么返回true。比如:</para>
-
-          <programlisting role="template">&lt;#if "piceous"?contains("ice")&gt;It contains "ice"&lt;/#if&gt;
-</programlisting>
-
-          <para>将会输出</para>
-
-          <programlisting role="output">It contains "ice"</programlisting>
-        </section>
-
-        <section xml:id="ref_builtin_string_date">
-          <title>date, time, datetime</title>
-
-          <indexterm>
-            <primary>type-casting</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>converting between types</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>date built-in</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>time built-in</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>datetime built-in</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>string to date</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>string to time</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>converting string to date</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>converting string to time</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>parsing string as date</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>parsing string as time</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>XML Schema date parsing</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>XML Schema time parsing</primary>
-          </indexterm>
-
-          <indexterm>
-            <primary>ISO 8601 parsing</primary>
-          </indexterm>
-
-          <para>字符串转换成日期值,时间或日期-时间值。需要一个由 <link
-          linkend="topic.dateTimeFormatSettings"><literal>date_format</literal>,
-          <literal>time_format</literal> 和
-          <literal>datetime_format</literal> 设置</link>指定的格式。
-		  如果字符串不是适当的格式,那么当访问该内建函数时,
-		  就会发生错误中止模板的处理。</para>
-
-          <programlisting role="template">&lt;#-- The date_format, time_format and datetime_format settings must match this format! --&gt;
-&lt;#assign someDate = "Oct 25, 1995"?date&gt;
-&lt;#assign someTime = "3:05:30 PM"?time&gt;
-&lt;#assign someDatetime = "Oct 25, 1995 03:05:00 PM"?datetime&gt;
-
-&lt;#-- Changing the setting value changes the expected format: --&gt;
-&lt;#setting datetime_format="iso"&gt;
-&lt;#assign someDatetime = "1995-10-25T15:05"?datetime&gt;
-</programlisting>
-
-          <para>也可以指定明确的格式,比如
-          <literal>?datetime.<replaceable>format</replaceable></literal> 或
-          <literal>?datetime["<replaceable>format</replaceable>"]</literal>
-          (由于历史原因,也可以是
-          <literal>?datetime("<replaceable>format</replaceable>")</literal>),
-		  它们与 <literal>?date</literal> 和 <literal>?time</literal>是相同的。
-		  对于格式化值的语法和意义,可以参考 <link
-          linkend="topic.dateTimeFormatSettings"><literal>date_format</literal>,
-          <literal>time_format</literal> 和
-          <literal>datetime_format</literal> 设置</link> 的可能的值。 比如:</para>
-
-          <programlisting role="template">&lt;#-- Parsing XML Schema xs:date, xs:time and xs:dateTime values: --&gt;
-&lt;#assign someDate = "1995-10-25"?date.xs&gt;
-&lt;#assign someTime = "15:05:30"?time.xs&gt;
-&lt;#assign someDatetime = "1995-10-25T15:05:00"?datetime.xs&gt;
-
-&lt;#-- Parsing ISO 8601 (both extended and basic formats): --&gt;
-&lt;#assign someDatetime = "1995-10-25T15:05"?datetime.iso&gt;
-&lt;#assign someDatetime = "19951025T1505"?datetime.iso&gt;
-
-&lt;#-- Parsing with SimpleDateFormat patterns: --&gt;
-&lt;#assign someDate = "10/25/1995"?date("MM/dd/yyyy")&gt;
-&lt;#assign someTime = "15:05:30"?time("HH:mm:ss")&gt;
-&lt;#assign someDatetime = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")&gt;</programlisting>
-
-          <para>避免误解,左侧值无需是字符串文本。比如,当从XML结点
-		  (此处的所有值都是未被解析的字符串)读取数据,那么就需要这样来做
-          <literal>order.confirmDate?date.xs</literal>,将字符串转化成真实的日期。</para>
-
-          <para>当然,格式也可以是一个变量,比如:
-          <literal>"<replaceable>...</replaceable>"?datetime[myFormat]</literal>。</para>
-        </section>
-
-        <section xml:id="ref_builtin_ends_with">
-          <title>ends_with</title>
-
-          <indexterm>
-            <primary>ends_with built-in</primary>
-          </indexterm>
-
-          <para>返回是否这个字符串以参数中指定的子串结尾。
-		  比如 <literal>"ahead"?ends_with("head")</literal> 返回布尔值 
-		  <literal>true</literal>。<literal>"head"?ends_with("head")</literal> 
-		  也返回 <literal>true</literal>。</para>
-        </section>
-
-        <section xml:id="ref_builtin_ensure_ends_with">
-          <title>ensure_ends_with</title>
-
-          <indexterm>
-            <primary>ensure_ends_with built-in</primary>
-          </indexterm>
-
-          <note>
-            <para>该内建函数从 FreeMarker 2.3.21 版本开始可用</para>
-          </note>
-
-          <para>如果字符串没有以第一个参数指定的子串结尾,
-		  那么就会将它加到字符串后面,否则返回原字符串。比如,
-          <literal>"foo"?ensure_ends_with("/")</literal> 和
-          <literal>"foo/"?ensure_ends_with("/")</literal> 返回
-          <literal>"foo/"</literal>。</para>
-        </section>
-
-        <section xml:id="ref_builtin_ensure_starts_with">
-          <title>ensure_starts_with</title>
-
-          <indexterm>
-            <primary>ensure_ends_with built-in</primary>
-          </indexterm>
-
-          <note>
-            <para>该内建函数从 FreeMarker 2.3.21 版本开始可用</para>
-          </note>
-
-          <para>如果字符串没有以第一个参数指定的子串开头,
-		  那么就会将它加到字符串开头,否则返回原字符串。比如,
-          <literal>"foo"?ensure_starts_with("/")</literal> 和
-          <literal>"/foo"?ensure_starts_with("/")</literal> 返回
-          <literal>"/foo"</literal>。</para>
-
-          <para>如果指定两个参数,那么第一个参数就被解释成Java正则表达式,
-		  如果它不匹配字符串的开头,那么第二个参数指定的字符串就会添加到字符串开头。
-		  比如 <literal>someURL?ensure_starts_with("[a-zA-Z]+://", "http://")</literal> 
-		  就会检查如果字符串是否以 <literal>"[a-zA-Z]+://"</literal> 开头
-		  (请注意,不需要 <literal>^</literal>),如果不是的话,就添加
-		  <literal>"http://"</literal>。</para>
-
-          <para>该方法也接受第三个<link
-          linkend="ref_builtin_string_flags">标志位参数</link>。因为调用两个参数暗指
-		  <literal>"r"</literal>(也就是正则表达式模式),那么就需要第三个参数了。
-		  值得注意的一点是当不需要第一参数被解释成正则表达式,而只是普通文本,
-		  但是又想让比较是大小写敏感的,那么此时就需要使用 <literal>"i"</literal>
-		  作为第三个参数。</para>
-        </section>
-
-        <section xml:id="ref_builtin_groups">
-          <title>groups</title>
-
-          <indexterm>
-            <primary>groups built-in</primary>
-          </indexterm>
-
-          <para>这个函数只作用于内建函数 <literal>matches</literal> 
-		  的结果。请参考 <link
-          linkend="ref_builtin_matches">这里...</link>。</para>
-        </section>
-
-        <section xml:id="ref_builtin_html">
-          <title>html</title>
-
-          <indexterm>
-            <primary>escaping</primary>
-
-            <secondary>output</secondary>
-          </indexterm>
-
-          <indexterm>
-            <primary>html built-in</primary>
-          </indexterm>
-
-          <para>字符串按照HTML标记输出。也就是说,下面字符串将会被替代:</para>
-
-          <itemizedlist spacing="compact">
-            <listitem>
-              <para><literal>&lt;</literal> 替换为
-              <literal>&amp;lt;</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>&gt;</literal> 替换为
-              <literal>&amp;gt;</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>&amp;</literal> 替换为
-              <literal>&amp;amp;</literal></para>
-            </listitem>
-
-            <listitem>
-              <para><literal>"</literal> 替换为
-              <literal>&amp;quot;</literal></para>
-            </listitem>
-
-            <listitem>
-              <para>如果程序员设置了FreeMarker(将 <literal>incompatible_improvements</literal> 
-			  设置为 <literal>2.3.20</literal> 或更高;更多内容请参考 <link
-              xlink:href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setIncompatibleImprovements%28freemarker.core.Version%29">这里</link>),那么
... 21570 lines suppressed ...


[freemarker] 04/05: Manual: Random minor improvements

Posted by dd...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git

commit f6cd05d971d1914cea8a38a2436f7bd2f1629cdc
Author: ddekany <dd...@apache.org>
AuthorDate: Thu Jan 5 01:03:54 2023 +0100

    Manual: Random minor improvements
---
 src/manual/en_US/book.xml | 51 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 33 insertions(+), 18 deletions(-)

diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index 1af11485..2ac26041 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -813,6 +813,16 @@ All Rights Reserved.
                 </listitem>
               </itemizedlist>
             </listitem>
+
+            <listitem>
+              <para><literal>product.id?c</literal> formats
+              <literal>product.id</literal> (let's say that's a number, the
+              technical ID of the product in our database) so that it can be
+              safely parsed by a computer process. This is important, as
+              <literal>${product.id}</literal> would format it for human
+              audience, which may contains more complicated (like localized,
+              grouped, etc.) formatting.</para>
+            </listitem>
           </itemizedlist>
 
           <para>Some built-ins require parameters to specify the behavior
@@ -4376,19 +4386,19 @@ ${("green " + "mouse")?upper_case}  &lt;#-- GREEN MOUSE --&gt;
           <para>since German people use comma as decimal separator.</para>
 
           <warning>
-            <para>As you can see, interpolations print for human audience (by
-            default at least), as opposed to ''computer audience''. In some
-            cases this is not good, like when you print a database record ID
-            as the part of an URL or as an invisible field value in a HTML
-            form, or when you print CSS/JavaScript numerical literals, because
-            these printed values will be read by computer programs and not by
-            humans. Most computer programs are very particular about the
-            format of the numbers, and understand only a kind of simple US
-            number formatting. For that, use the <link
-            linkend="ref_builtin_c"><literal>c</literal></link> (stands for
-            ''computer audience'') built-in, for example:</para>
-
-            <programlisting role="template">&lt;a href="/shop/productdetails?id=${product.id?c}"&gt;Details...&lt;/a&gt;</programlisting>
+            <para>When the number you print will be read by some computer
+            process, always use the <link linkend="ref_builtin_c"><link
+            linkend="ref_builtin_c"><literal>c</literal></link>
+            built-in</link>, to get rid of any localized, or otherwise fancy
+            formatting! Like when you print a database record ID as the part
+            of an URL or as an invisible field value in a HTML form, or when
+            you print CSS/JavaScript numerical literals. Example:</para>
+
+            <programlisting role="template">&lt;a href="/shop/productdetails?id=${product.id<emphasis>?c</emphasis>}"&gt;Details...&lt;/a&gt;</programlisting>
+
+            <para>That <literal>?c</literal> there formats the number with a
+            simple US format, which most computer processes will
+            understand.</para>
           </warning>
         </section>
 
@@ -4452,7 +4462,8 @@ ${("green " + "mouse")?upper_case}  &lt;#-- GREEN MOUSE --&gt;
           error.</para>
 
           <para>When you want to generate JavaScript or other computer
-          language parts, then <literal>${someBoolean?c}</literal>
+          language parts, then
+          <literal>${<replaceable>someBoolean</replaceable>?c}</literal>
           (<quote>c</quote> stands for computer audience) should be used to
           print true/false. (Remember that <literal>?c</literal> was also used
           to print numbers for computer audience.)</para>
@@ -6646,9 +6657,9 @@ That's all.</programlisting>
         beginning of the application (possibly servlet) life-cycle:</para>
 
         <programlisting role="unspecified">// Create your Configuration instance, and specify if up to what FreeMarker
-// version (here 2.3.29) do you want to apply the fixes that are not 100%
+// version (here 2.3.32) do you want to apply the fixes that are not 100%
 // backward-compatible. See the Configuration JavaDoc for details.
-Configuration cfg = new Configuration(Configuration.VERSION_2_3_29);
+Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
 
 // Specify the source where the template files come from. Here I set a
 // plain directory for it, but non-file-system sources are possible too:
@@ -6672,7 +6683,10 @@ cfg.setLogTemplateExceptions(false);
 cfg.setWrapUncheckedExceptions(true);
 
 // Do not fall back to higher scopes when reading a null loop variable:
-cfg.setFallbackOnNullLoopVariable(false);</programlisting>
+cfg.setFallbackOnNullLoopVariable(false);
+
+// To accomodate to how JDBC returns values; see Javadoc!
+cfg.setSQLDateAndTimeTimeZone(TimeZone.getDefault());</programlisting>
 
         <para>From now you should use this <emphasis>single</emphasis>
         configuration instance (i.e., its a singleton). Note however that if a
@@ -6944,7 +6958,7 @@ public class Test {
         /* You should do this ONLY ONCE in the whole application life-cycle:        */
 
         /* Create and adjust the configuration singleton */
-        Configuration cfg = new Configuration(Configuration.VERSION_2_3_29);
+        Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
         cfg.setDirectoryForTemplateLoading(new File("<replaceable>/where/you/store/templates</replaceable>"));
         // Recommended settings for new projects:
         cfg.setDefaultEncoding("UTF-8");
@@ -6952,6 +6966,7 @@ public class Test {
         cfg.setLogTemplateExceptions(false);
         cfg.setWrapUncheckedExceptions(true);
         cfg.setFallbackOnNullLoopVariable(false);
+        cfg.setSQLDateAndTimeTimeZone(TimeZone.getDefault());
 
         /* ------------------------------------------------------------------------ */
         /* You usually do these for MULTIPLE TIMES in the application life-cycle:   */


[freemarker] 03/05: Fixed outdated try.freemarker link.

Posted by dd...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git

commit b65c56ef515324b62dfbaf7a07aaa981b03a2aad
Author: ddekany <dd...@apache.org>
AuthorDate: Wed Jan 4 23:29:17 2023 +0100

    Fixed outdated try.freemarker link.
---
 src/manual/en_US/book.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index 8569625e..1af11485 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -417,8 +417,8 @@
         and "directive" synonyms.)</para>
 
         <note>
-          <para>You can easily try writing templates on <link
-          xlink:href="http://freemarker-online.kenshoo.com/">http://freemarker-online.kenshoo.com/</link></para>
+          <para>You can easily try writing templates on <olink
+          targetdoc="onlineTemplateTester"/></para>
         </note>
 
         <section>


[freemarker] 01/05: (Minor typos)

Posted by dd...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git

commit 956067cb1f49d9f8fe1c21456545a7a22dea2d03
Author: ddekany <dd...@apache.org>
AuthorDate: Wed Jan 4 23:22:01 2023 +0100

    (Minor typos)
---
 src/main/java/freemarker/core/ExtendedDecimalFormatParser.java | 4 ++--
 src/main/java/freemarker/ext/jsp/JspTagModelBase.java          | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/main/java/freemarker/core/ExtendedDecimalFormatParser.java b/src/main/java/freemarker/core/ExtendedDecimalFormatParser.java
index 02e0fbaa..db47c9aa 100644
--- a/src/main/java/freemarker/core/ExtendedDecimalFormatParser.java
+++ b/src/main/java/freemarker/core/ExtendedDecimalFormatParser.java
@@ -264,7 +264,7 @@ class ExtendedDecimalFormatParser {
         }
 
         String currencySymbol = null;  // Exceptional, as must be applied after "currency code"
-        fetchParamters: do {
+        fetchParameters: do {
             int namePos = pos;
             String name = fetchName();
             if (name == null) {
@@ -308,7 +308,7 @@ class ExtendedDecimalFormatParser {
                 skipWS();
             } else {
                 if (pos == ln) {
-                    break fetchParamters;
+                    break fetchParameters;
                 }
                 if (pos == paramEndPos) {
                     throw newExpectedSgParseException("parameter separator whitespace or comma");
diff --git a/src/main/java/freemarker/ext/jsp/JspTagModelBase.java b/src/main/java/freemarker/ext/jsp/JspTagModelBase.java
index 2c4d57b2..0fc96a49 100644
--- a/src/main/java/freemarker/ext/jsp/JspTagModelBase.java
+++ b/src/main/java/freemarker/ext/jsp/JspTagModelBase.java
@@ -119,7 +119,7 @@ class JspTagModelBase {
                                 "). See cause exception for the more specific cause...");
                         if (e instanceof IllegalArgumentException && !(setterType.isAssignableFrom(String.class))
                                 && argArray[0] != null && argArray[0] instanceof String) {
-                            desc.tip("This problem is often caused by unnecessary parameter quotation. Paramters "
+                            desc.tip("This problem is often caused by unnecessary parameter quotation. Parameters "
                                     + "aren't quoted in FTL, similarly as they aren't quoted in most languages. "
                                     + "For example, these parameter assignments are wrong: ",
                                     "<@my.tag p1=\"true\" p2=\"10\" p3=\"${someVariable}\" p4=\"${x+1}\" />",


[freemarker] 05/05: (Missing list of predefined values in output_format JavaDoc)

Posted by dd...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git

commit 9f120dfe6c73c20ac22595ac7bba92640186a5b4
Author: ddekany <dd...@apache.org>
AuthorDate: Thu Jan 5 01:06:02 2023 +0100

    (Missing list of predefined values in output_format JavaDoc)
---
 src/main/java/freemarker/core/Configurable.java | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java
index a70e247e..bf6e3aab 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -2413,9 +2413,11 @@ public class Configurable {
      *       
      *   <li><p>{@code "output_format"}:
      *       See {@link Configuration#setOutputFormat(OutputFormat)}.
-     *       <br>String value: {@code "default"} (case insensitive) for the default, or an
-     *       <a href="#fm_obe">object builder expression</a> that gives an {@link OutputFormat}, for example
-     *       {@code HTMLOutputFormat} or {@code XMLOutputFormat}.
+     *       <br>String value: {@code "default"} (case insensitive) for the default,
+     *       one of {@code undefined}, {@code HTML}, {@code XHTML}, {@code XML}, {@code RTF}, {@code plainText},
+     *       {@code CSS}, {@code JavaScript}, {@code JSON},
+     *       or an <a href="#fm_obe">object builder expression</a> that gives an {@link OutputFormat}, for example
+     *       {@code HTMLOutputFormat}, or {@code com.example.MyOutputFormat()}.
      *
      *   <li><p>{@code "registered_custom_output_formats"}:
      *       See {@link Configuration#setRegisteredCustomOutputFormats(Collection)}.