Mailing-List: contact notifications-help@freemarker.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@freemarker.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
From: ddekany@apache.org
To: notifications@freemarker.incubator.apache.org
Date: Tue, 16 May 2017 17:40:34 -0000
Message-Id: <9a456bbc6cde4eb7bbeba046c1544c34@git.apache.org>
In-Reply-To: <e1eb4f4963c644baa2ab45ff21f409bb@git.apache.org>
References: <e1eb4f4963c644baa2ab45ff21f409bb@git.apache.org>
Subject: [2/5] incubator-freemarker git commit: Moved Manual (documentation)
 related things to its own module,
 freemarker-manual. Because it covers all modules, not just freemarker-core,
 that's the logical place for it.
archived-at: Tue, 16 May 2017 17:40:54 -0000

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen-help/editors-readme.txt
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen-help/editors-readme.txt b/freemarker-manual/src/main/docgen/en_US/docgen-help/editors-readme.txt
new file mode 100644
index 0000000..24436e8
--- /dev/null
+++ b/freemarker-manual/src/main/docgen/en_US/docgen-help/editors-readme.txt
@@ -0,0 +1,130 @@
+/*
+ * 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.
+ */
+ 
+Guide to FreeMarker Manual for Editors
+======================================
+
+Non-technical
+-------------
+
+- The Template Author's Guide is for Web designers. Assume that a
+  designer is not a programmer, (s)he doesn't even know what is Java.
+  Forget that FM is implemented in Java when you edit the Template
+  Author's Guide. Try to avoid technical writing.
+
+- In the Guide chapters, be careful not to mention things that were
+  not explained earlier. The Guide chapters should be understandable
+  if you read them continuously.
+
+- If you add a new topic or term, don't forget to add it to the Index.
+  Also, consider adding entries for it to the Glossary.
+
+- Don't use too sophisticated English. Use basic words and grammar.
+
+
+Technical
+---------
+
+- For the editing use XXE (XMLmind XML Editor), with its default XML
+  *source* formatting settings (identation, max line length and like).
+  You should install the "DocBook 5 for Freemarker" addon, which you can
+  find inside the "docgen" top-level SVN module.
+
+- The HTML is generated with Docgen (docgen.jar), which will check some
+  of the rules described here. To invoke it, issue "ant manual" from
+  the root of the "freemarker" module. (Note: you may need to check out
+  and build "docgen" first.)
+
+- Understand all document conventions in the Preface chapter. Note that
+  all "programlisting"-s should have a "role" attribute with a value that
+  is either: "template", "dataModel", "output", "metaTemplate" or
+  "unspecified". (If you miss this, the XXE addon will show the
+  "programlisting" in red.)
+
+- Verbatim content in flow text:
+
+  * In flow text, all data object names, class names, FTL fragments,
+    HTML fragments, and all other verbatim content is inside "literal"
+    element.
+
+  * Use replaceable element inside literal element for replaceable
+    parts and meta-variables like:
+    <literal&lt;if <replaceable>condition</replaceable>></literal>
+    <literal><replaceable>templateDir</replaceable>/copyright.ftl</literal>
+
+- Hierarchy:
+
+  * The hierarchy should look like:
+
+      book -> part -> chapter -> section -> section -> section -> section
+
+    where the "part" and the "section"-s are optional.
+    Instead of chapter you may have "preface" or "appendix".
+
+  * Don't use "sect1", "sect2", etc. Instead nest "section"-s into each other,
+    but not deeper than 3 levels.
+
+  * Use "simplesect" if you want to divide up something visually, but
+    you don't want those sections to appear in the ToC, or go into their own
+    HTML page. "simplesect"-s can appear under all "section" nesting
+    levels, and they always look the same regardless of the "section"
+    nesting levels.
+
+- Lists:
+
+  * When you have list where the list items are short (a few words),
+    you should give spacing="compact" to the "itemizedlist" or
+    "orderedlist" element.
+
+  * Don't putting listings inside "para"-s. Put them between "para"-s instead.
+
+- Xrefs, id-s, links:
+
+  * id-s of parts, chapters, sections and similar elements must
+    contain US-ASCII lower case letters, US-ASCII numbers, and
+    underscore only. id-s of parts and chapters are used as the
+    filenames of HTML-s generated for that block.
+    When you find out the id, deduce it from the position in the ToC
+    hierarchy. The underscore is used as the separator between the path
+    steps.
+
+  * All other id-s must use prefix:
+    - example: E.g.: id="example.foreach"
+    - ref: Reference information...
+      * directive: about a directive. E.g.: "ref.directive.foreach"
+      * builtin
+    - gloss: Term in the Glossary
+    - topic: The recommended point of document in a certain topic
+      * designer: for designers.
+          E.g.: id="topic.designer.methodDataObject"
+      * programmer: for programmers
+      * or omit the secondary category if it is for everybody
+    - misc: Anything doesn't fit in the above categories
+
+  * When you refer to a part, chapter or section, often you should use
+    xref, not link. The xreflabel attribute of the link-end should not be set;
+    then it's deduced from the titles.
+
+- The "book" element must have this attribute: conformance="docgen"
+
+- It sometimes happens that you want to change some content that you see in
+  the generated output, which you can't find in the DocBook XML. In such case,
+  check the contents docgen.cjson, which should be in the same directory as
+  the XML. If it's not there either, it's perhaps hard-wired into the
+  templates in docgen.

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen-misc/copyrightComment.txt
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen-misc/copyrightComment.txt b/freemarker-manual/src/main/docgen/en_US/docgen-misc/copyrightComment.txt
new file mode 100644
index 0000000..60b675e
--- /dev/null
+++ b/freemarker-manual/src/main/docgen/en_US/docgen-misc/copyrightComment.txt
@@ -0,0 +1,16 @@
+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.

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen-misc/googleAnalytics.html
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen-misc/googleAnalytics.html b/freemarker-manual/src/main/docgen/en_US/docgen-misc/googleAnalytics.html
new file mode 100644
index 0000000..759564e
--- /dev/null
+++ b/freemarker-manual/src/main/docgen/en_US/docgen-misc/googleAnalytics.html
@@ -0,0 +1,14 @@
+<!--
+  This snippet was generated by Google Analytics.
+  Thus, the standard FreeMarker copyright comment was intentionally omitted.
+  <#DO_NOT_UPDATE_COPYRIGHT>
+-->
+<script>
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+  ga('create', 'UA-55420501-1', 'auto');
+  ga('send', 'pageview');
+</script>

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/model2sketch_with_alpha.png
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/model2sketch_with_alpha.png b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/model2sketch_with_alpha.png
new file mode 100644
index 0000000..ce120cc
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/model2sketch_with_alpha.png differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/odg-convert-howto.txt
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/odg-convert-howto.txt b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/odg-convert-howto.txt
new file mode 100644
index 0000000..e55acec
--- /dev/null
+++ b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/odg-convert-howto.txt
@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+ 
+Converting to SVG:
+1. Open the ODG file with Libeoffice/OpenOffice Draw
+2. Ctrl+A to select all objects
+3. File/Export..., chose SVG format, and then tick "Selection"
+4. Check the result. If contour lines at the right and bottom edge of the
+   figure are partically clipped (stroke width is halved), set a stroke with
+   other than 0 for all shapes.
+   
+Converting to a decent quality (though non-transparent) PNG:
+1. Open the ODG file with Libeoffice/OpenOffice Draw
+2. Export to PDF
+3. Open PDF in Adobe Acrobat Reader
+4. Go to Adobe Acrobat Reader preferences and set it to not use subpixel
+   anti-aliasing, just normal anti-aliasing. They used to call this LCD vs
+   Monitor mode.
+5. Zoom in/out until you get the desired size in pixels, take a
+   screen shot, crop it in some image editor, save it as PNG.
+   
+Converting to transparent but somewhat ugly PNG:
+1. Convert to SVG as described earlier
+2. Use Apache Batik Rasterizer command line utility like:
+   $BARIK_INSTALLATION\batik-rasterizer-1.8.jar -dpi 72 -m image/png ${FIGURE}.svg
+   If Batik fails (as it doesn't support all SVG features), use Inkscape.
+   Of course avoid supixel anti-aliasing, as it's not device independent.

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/overview.odg
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/overview.odg b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/overview.odg
new file mode 100644
index 0000000..0533b7c
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/overview.odg differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/tree_with_alpha.png
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/tree_with_alpha.png b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/tree_with_alpha.png
new file mode 100644
index 0000000..dc4fba8
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/docgen-originals/figures/tree_with_alpha.png differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/docgen.cjson
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/docgen.cjson b/freemarker-manual/src/main/docgen/en_US/docgen.cjson
new file mode 100644
index 0000000..076e8f3
--- /dev/null
+++ b/freemarker-manual/src/main/docgen/en_US/docgen.cjson
@@ -0,0 +1,132 @@
+﻿//charset: 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.
+
+deployUrl: "http://freemarker.org/docs/"
+onlineTrackerHTML: "docgen-misc/googleAnalytics.html"
+searchKey: "003127866208504630097:arjqbv_znfw"
+validation: {
+  programlistingsRequireRole
+  // programlistingsRequireLanguage
+  maximumProgramlistingWidth: 100
+}
+showXXELogo
+generateEclipseTOC
+// eclipse: {
+//  link_to: "freemarker-toc.xml#ManualLink"
+// }
+
+removeNodesWhenOnline: [ "preface" ]
+
+copyrightHolder: "The Apache Software Foundation"
+copyrightHolderSite: "http://apache.org/"
+copyrightSuffix: "Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation."
+copyrightStartYear: 1999
+copyrightCommentFile: "docgen-misc/copyrightComment.txt"
+
+seoMeta: {
+  "dgui_quickstart": {
+    "title": "Getting Started with template writing"
+  }
+  "pgui_quickstart": {
+    "title": "Getting Started with the Java API"
+  }
+}
+
+logo: {
+  href: "http://freemarker.org"
+  src: logo.png,
+  alt: "FreeMarker"
+}
+
+olinks: {
+  homepage: "http://freemarker.org/"
+  api: "api/index.html"
+  
+  // Homepage links:
+  freemarkerdownload: "http://freemarker.org/freemarkerdownload.html"
+  contribute: "http://freemarker.org/contribute.html"
+  history: "http://freemarker.org/history.html"
+  what-is-freemarker: "http://freemarker.org/"
+  mailing-lists: "http://freemarker.org/mailing-lists.html"
+  
+  // External URL-s:
+  onlineTemplateTester: "http://freemarker-online.kenshoo.com/"
+  twitter: "https://twitter.com/freemarker"
+  sourceforgeProject: "https://sourceforge.net/projects/freemarker/"
+  githubProject: "https://github.com/freemarker/freemarker"
+  newBugReport: "https://issues.apache.org/jira/browse/FREEMARKER/"
+  newStackOverflowQuestion: "http://stackoverflow.com/questions/ask?tags=freemarker"
+}
+
+internalBookmarks: {
+  "Alpha. index": alphaidx
+  "Glossary": gloss
+  "Expressions": exp_cheatsheet
+  "?builtins": ref_builtins_alphaidx
+  "#directives": ref_directive_alphaidx
+  ".spec_vars": ref_specvar
+  "FAQ": app_faq
+}
+
+tabs: {
+  "Home": "olink:homepage"
+  "Manual": ""  // Empty => We are here
+  "Java API": "olink:api"
+}
+
+// Available icons:
+// .icon-heart
+// .icon-bug
+// .icon-download
+// .icon-star
+secondaryTabs: {
+  "Contribute": { class: "icon-heart", href: "olink:contribute" }
+  "Report a Bug": { class: "icon-bug", href: "olink:newBugReport" }
+  "Download": { class: "icon-download", href: "olink:freemarkerdownload" }
+}
+
+footerSiteMap: {
+  "Overview": {
+    "What is FreeMarker?": "olink:what-is-freemarker"
+    "Download": "olink:freemarkerdownload"
+    "Version history": "id:app_versions"
+    "About us": "olink:history"
+    "License": "id:app_license"
+  }
+  "Handy stuff": {
+    "Try template online": "olink:onlineTemplateTester"
+    "Expressions cheatsheet": "id:exp_cheatsheet"
+    "#directives": "id:ref_directive_alphaidx"
+    "?built_ins": "id:ref_builtins_alphaidx"
+    ".special_vars": "id:ref_specvar"
+  }
+  "Community": {
+    "FreeMarker on Github": "olink:githubProject"
+    "Follow us on Twitter": "olink:twitter"
+    "Report a bug": "olink:newBugReport"
+    "Ask a question": "olink:newStackOverflowQuestion"
+    "Mailing lists": "olink:mailing-lists"
+  }
+}
+
+socialLinks: {
+  "Github": { class: "github", href: "olink:githubProject" }
+  "Twitter": { class: "twitter", href: "olink:twitter" }
+  "Stack Overflow": { class: "stack-overflow", href: "olink:newStackOverflowQuestion" }
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/favicon.png
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/favicon.png b/freemarker-manual/src/main/docgen/en_US/favicon.png
new file mode 100644
index 0000000..ce0de20
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/favicon.png differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/figures/model2sketch.png
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/figures/model2sketch.png b/freemarker-manual/src/main/docgen/en_US/figures/model2sketch.png
new file mode 100644
index 0000000..93f9a6b
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/figures/model2sketch.png differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/figures/overview.png
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/figures/overview.png b/freemarker-manual/src/main/docgen/en_US/figures/overview.png
new file mode 100644
index 0000000..b32e0bd
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/figures/overview.png differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/figures/tree.png
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/figures/tree.png b/freemarker-manual/src/main/docgen/en_US/figures/tree.png
new file mode 100644
index 0000000..dcd9bf3
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/figures/tree.png differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/main/docgen/en_US/logo.png
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/main/docgen/en_US/logo.png b/freemarker-manual/src/main/docgen/en_US/logo.png
new file mode 100644
index 0000000..193dc11
Binary files /dev/null and b/freemarker-manual/src/main/docgen/en_US/logo.png differ

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/AutoEscapingExample.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/AutoEscapingExample.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/AutoEscapingExample.java
new file mode 100644
index 0000000..f872e41
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/AutoEscapingExample.java
@@ -0,0 +1,72 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import org.apache.freemarker.core.Configuration;
+import org.apache.freemarker.test.TemplateTest;
+import org.apache.freemarker.test.TestConfigurationBuilder;
+import org.junit.Test;
+
+public class AutoEscapingExample extends TemplateTest {
+
+    @Test
+    public void testInfoBox() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-infoBox.ftlh");
+    }
+
+    @Test
+    public void testCapture() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-capture.ftlh");
+    }
+
+    @Test
+    public void testMarkup() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-markup.ftlh");
+    }
+
+    @Test
+    public void testConvert() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-convert.ftlh");
+    }
+
+    @Test
+    public void testConvert2() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-convert2.ftl");
+    }
+
+    @Test
+    public void testStringLiteral() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-stringLiteral.ftlh");
+    }
+
+    @Test
+    public void testStringLiteral2() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-stringLiteral2.ftlh");
+    }
+
+    @Test
+    public void testStringConcat() throws Exception {
+        assertOutputForNamed("AutoEscapingExample-stringConcat.ftlh");
+    }
+
+    @Override
+    protected Configuration createDefaultConfiguration() throws Exception {
+        return new TestConfigurationBuilder(AutoEscapingExample.class).build();
+    }
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/BaseNTemplateNumberFormatFactory.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/BaseNTemplateNumberFormatFactory.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/BaseNTemplateNumberFormatFactory.java
new file mode 100644
index 0000000..f987dcd
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/BaseNTemplateNumberFormatFactory.java
@@ -0,0 +1,128 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import java.util.Locale;
+
+import org.apache.freemarker.core.Environment;
+import org.apache.freemarker.core.model.TemplateModelException;
+import org.apache.freemarker.core.model.TemplateNumberModel;
+import org.apache.freemarker.core.util._NumberUtil;
+import org.apache.freemarker.core.util._StringUtil;
+import org.apache.freemarker.core.valueformat.InvalidFormatParametersException;
+import org.apache.freemarker.core.valueformat.TemplateFormatUtil;
+import org.apache.freemarker.core.valueformat.TemplateNumberFormat;
+import org.apache.freemarker.core.valueformat.TemplateNumberFormatFactory;
+import org.apache.freemarker.core.valueformat.TemplateValueFormatException;
+import org.apache.freemarker.core.valueformat.UnformattableValueException;
+
+/**
+ * Shows a number in base N number system. Can only format numbers that fit into an {@code int},
+ * however, optionally you can specify a fallback format. This format has one required parameter,
+ * the numerical system base. That can be optionally followed by "|" and a fallback format.
+ */
+public class BaseNTemplateNumberFormatFactory extends TemplateNumberFormatFactory {
+
+    public static final BaseNTemplateNumberFormatFactory INSTANCE
+            = new BaseNTemplateNumberFormatFactory();
+    
+    private BaseNTemplateNumberFormatFactory() {
+        // Defined to decrease visibility
+    }
+    
+    @Override
+    public TemplateNumberFormat get(String params, Locale locale, Environment env)
+            throws InvalidFormatParametersException {
+        TemplateNumberFormat fallbackFormat;
+        {
+            int barIdx = params.indexOf('|');
+            if (barIdx != -1) {
+                String fallbackFormatStr = params.substring(barIdx + 1);
+                params = params.substring(0, barIdx);
+                try {
+                    fallbackFormat = env.getTemplateNumberFormat(fallbackFormatStr, locale);
+                } catch (TemplateValueFormatException e) {
+                    throw new InvalidFormatParametersException(
+                            "Couldn't get the fallback number format (specified after the \"|\"), "
+                            + _StringUtil.jQuote(fallbackFormatStr) + ". Reason: " + e.getMessage(),
+                            e);
+                }
+            } else {
+                fallbackFormat = null;
+            }
+        }
+        
+        int base;
+        try {
+            base = Integer.parseInt(params);
+        } catch (NumberFormatException e) {
+            if (params.length() == 0) {
+                throw new InvalidFormatParametersException(
+                        "A format parameter is required to specify the numerical system base.");
+            }
+            throw new InvalidFormatParametersException(
+                    "The format paramter must be an integer, but was (shown quoted): "
+                    + _StringUtil.jQuote(params));
+        }
+        if (base < 2) {
+            throw new InvalidFormatParametersException("A base must be at least 2.");
+        }
+        return new BaseNTemplateNumberFormat(base, fallbackFormat);
+    }
+
+    private static class BaseNTemplateNumberFormat extends TemplateNumberFormat {
+
+        private final int base;
+        private final TemplateNumberFormat fallbackFormat;
+        
+        private BaseNTemplateNumberFormat(int base, TemplateNumberFormat fallbackFormat) {
+            this.base = base;
+            this.fallbackFormat = fallbackFormat;
+        }
+        
+        @Override
+        public String formatToPlainText(TemplateNumberModel numberModel)
+                throws TemplateModelException, TemplateValueFormatException {
+            Number n = TemplateFormatUtil.getNonNullNumber(numberModel);
+            try {
+                return Integer.toString(_NumberUtil.toIntExact(n), base);
+            } catch (ArithmeticException e) {
+                if (fallbackFormat == null) {
+                    throw new UnformattableValueException(
+                            n + " doesn't fit into an int, and there was no fallback format "
+                            + "specified.");
+                } else {
+                    return fallbackFormat.formatToPlainText(numberModel);
+                }
+            }
+        }
+
+        @Override
+        public boolean isLocaleBound() {
+            return false;
+        }
+
+        @Override
+        public String getDescription() {
+            return "base " + base;
+        }
+        
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples.java
new file mode 100644
index 0000000..8d6ce99
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples.java
@@ -0,0 +1,105 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import static org.junit.Assert.*;
+
+import java.io.IOException;
+
+import org.apache.freemarker.core.TemplateConfiguration;
+import org.apache.freemarker.core.outputformat.impl.HTMLOutputFormat;
+import org.apache.freemarker.core.outputformat.impl.RTFOutputFormat;
+import org.apache.freemarker.core.outputformat.impl.XMLOutputFormat;
+import org.apache.freemarker.core.templateresolver.ConditionalTemplateConfigurationFactory;
+import org.apache.freemarker.core.templateresolver.FileExtensionMatcher;
+import org.apache.freemarker.core.templateresolver.FirstMatchTemplateConfigurationFactory;
+import org.apache.freemarker.core.templateresolver.OrMatcher;
+import org.apache.freemarker.core.templateresolver.PathGlobMatcher;
+import org.apache.freemarker.test.TemplateTest;
+import org.apache.freemarker.test.TestConfigurationBuilder;
+import org.junit.Test;
+
+public class ConfigureOutputFormatExamples extends TemplateTest {
+    
+    @Test
+    public void test() throws Exception {
+        addTemplate("mail/t.ftl", "");
+        addTemplate("t.html", "");
+        addTemplate("t.htm", "");
+        addTemplate("t.xml", "");
+        addTemplate("t.rtf", "");
+
+        example2(true);
+        example2(false);
+        example3(true);
+        example3(false);
+    }
+
+    private void example2(boolean javaCfg) throws IOException {
+        setConfiguration(
+                javaCfg
+                        ? new TestConfigurationBuilder()
+                                .templateConfigurations(
+                                        new ConditionalTemplateConfigurationFactory(
+                                                new PathGlobMatcher("mail/**"),
+                                                new TemplateConfiguration.Builder()
+                                                        .outputFormat(HTMLOutputFormat.INSTANCE)
+                                                        .build()))
+                                .build()
+                        : new TestConfigurationBuilder()
+                                .settings(loadPropertiesFile("ConfigureOutputFormatExamples1.properties"))
+                                .build());
+        assertEquals(HTMLOutputFormat.INSTANCE, getConfiguration().getTemplate("mail/t.ftl").getOutputFormat());
+    }
+
+    private void example3(boolean javaCfg) throws IOException {
+        setConfiguration(
+                javaCfg
+                        ? new TestConfigurationBuilder()
+                                .templateConfigurations(
+                                        new FirstMatchTemplateConfigurationFactory(
+                                                new ConditionalTemplateConfigurationFactory(
+                                                        new FileExtensionMatcher("xml"),
+                                                        new TemplateConfiguration.Builder()
+                                                                .outputFormat(XMLOutputFormat.INSTANCE)
+                                                                .build()),
+                                                new ConditionalTemplateConfigurationFactory(
+                                                        new OrMatcher(
+                                                                new FileExtensionMatcher("html"),
+                                                                new FileExtensionMatcher("htm")),
+                                                        new TemplateConfiguration.Builder()
+                                                                .outputFormat(HTMLOutputFormat.INSTANCE)
+                                                                .build()),
+                                                new ConditionalTemplateConfigurationFactory(
+                                                        new FileExtensionMatcher("rtf"),
+                                                        new TemplateConfiguration.Builder()
+                                                                .outputFormat(RTFOutputFormat.INSTANCE)
+                                                                .build()))
+                                        .allowNoMatch(true))
+                                .build()
+                        : new TestConfigurationBuilder()
+                                .settings(loadPropertiesFile("ConfigureOutputFormatExamples2.properties"))
+                                .build());
+        assertEquals(HTMLOutputFormat.INSTANCE, getConfiguration().getTemplate("t.html").getOutputFormat());
+        assertEquals(HTMLOutputFormat.INSTANCE, getConfiguration().getTemplate("t.htm").getOutputFormat());
+        assertEquals(XMLOutputFormat.INSTANCE, getConfiguration().getTemplate("t.xml").getOutputFormat());
+        assertEquals(RTFOutputFormat.INSTANCE, getConfiguration().getTemplate("t.rtf").getOutputFormat());
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/CustomFormatsExample.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/CustomFormatsExample.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/CustomFormatsExample.java
new file mode 100644
index 0000000..afa2185
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/CustomFormatsExample.java
@@ -0,0 +1,83 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import java.io.IOException;
+import java.math.BigDecimal;
+import java.util.Date;
+
+import org.apache.freemarker.core.TemplateException;
+import org.apache.freemarker.core.valueformat.TemplateDateFormatFactory;
+import org.apache.freemarker.core.valueformat.TemplateNumberFormatFactory;
+import org.apache.freemarker.core.valueformat.impl.AliasTemplateDateFormatFactory;
+import org.apache.freemarker.core.valueformat.impl.AliasTemplateNumberFormatFactory;
+import org.apache.freemarker.test.TemplateTest;
+import org.apache.freemarker.test.TestConfigurationBuilder;
+import org.junit.Test;
+
+import com.google.common.collect.ImmutableMap;
+
+@SuppressWarnings("boxing")
+public class CustomFormatsExample extends TemplateTest {
+
+    @Test
+    public void aliases1() throws IOException, TemplateException {
+        setConfiguration(new TestConfigurationBuilder(this.getClass())
+            .customNumberFormats(ImmutableMap.<String, TemplateNumberFormatFactory>of(
+                    "price", new AliasTemplateNumberFormatFactory(",000.00"),
+                    "weight", new AliasTemplateNumberFormatFactory("0.##;; roundingMode=halfUp")))
+            .customDateFormats(ImmutableMap.<String, TemplateDateFormatFactory>of(
+                    "fileDate", new AliasTemplateDateFormatFactory("dd/MMM/yy hh:mm a"),
+                    "logEventTime", new AliasTemplateDateFormatFactory("iso ms u")
+                    ))
+            .build());
+
+        addToDataModel("p", 10000);
+        addToDataModel("w", new BigDecimal("10.305"));
+        addToDataModel("fd", new Date(1450904944213L));
+        addToDataModel("let", new Date(1450904944213L));
+        
+        assertOutputForNamed("CustomFormatsExample-alias1.ftlh");
+    }
+
+    @Test
+    public void aliases2() throws IOException, TemplateException {
+        setConfiguration(new TestConfigurationBuilder(this.getClass())
+                .customNumberFormats(ImmutableMap.of(
+                        "base", BaseNTemplateNumberFormatFactory.INSTANCE,
+                        "oct", new AliasTemplateNumberFormatFactory("@base 8")))
+                .build());
+
+        assertOutputForNamed("CustomFormatsExample-alias2.ftlh");
+    }
+
+    @Test
+    public void modelAware() throws IOException, TemplateException {
+        setConfiguration(new TestConfigurationBuilder(this.getClass())
+                .customNumberFormats(ImmutableMap.<String, TemplateNumberFormatFactory>of(
+                        "ua", UnitAwareTemplateNumberFormatFactory.INSTANCE))
+                .numberFormat("@ua 0.####;; roundingMode=halfUp")
+                .build());
+
+        addToDataModel("weight", new UnitAwareTemplateNumberModel(1.5, "kg"));
+        
+        assertOutputForNamed("CustomFormatsExample-modelAware.ftlh");
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/GettingStartedExample.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/GettingStartedExample.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/GettingStartedExample.java
new file mode 100644
index 0000000..7a0a906
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/GettingStartedExample.java
@@ -0,0 +1,69 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import java.io.OutputStreamWriter;
+import java.io.Writer;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.apache.freemarker.core.Configuration;
+import org.apache.freemarker.core.Template;
+import org.apache.freemarker.core.TemplateExceptionHandler;
+import org.apache.freemarker.core.templateresolver.impl.ClassTemplateLoader;
+import org.junit.Test;
+
+public class GettingStartedExample {
+
+    @Test
+    public void main() throws Exception {
+        /* ------------------------------------------------------------------------ */    
+        /* You should do this ONLY ONCE in the whole application life-cycle:        */    
+    
+        /* Create the configuration singleton (using builder pattern) */
+        Configuration cfg = new Configuration.Builder(Configuration.VERSION_3_0_0)
+                .templateLoader(new ClassTemplateLoader(GettingStartedExample.class, ""))
+                .sourceEncoding(StandardCharsets.UTF_8)
+                .templateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER)
+                .logTemplateExceptions(false)
+                .build();
+
+        /* ------------------------------------------------------------------------ */    
+        /* You usually do these for MULTIPLE TIMES in the application life-cycle:   */    
+
+        /* Create a data-model */
+        Map<String, Object> root = new HashMap();
+        root.put("user", "Big Joe");
+        Product latest = new Product();
+        latest.setUrl("products/greenmouse.html");
+        latest.setName("green mouse");
+        root.put("latestProduct", latest);
+
+        /* Get the template (uses cache internally) */
+        Template temp = cfg.getTemplate("test.ftlh");
+
+        /* 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.
+    }
+    
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/Product.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/Product.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/Product.java
new file mode 100644
index 0000000..33b08d4
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/Product.java
@@ -0,0 +1,49 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+/**
+ * Product bean; note that it must be a public class!
+ */
+public class Product {
+
+    private String url;
+    private String name;
+
+    // As per the JavaBeans spec., this defines the "url" bean property
+    // It must be public!
+    public String getUrl() {
+        return url;
+    }
+
+    public void setUrl(String url) {
+        this.url = url;
+    }
+
+    // As per the JavaBean spec., this defines the "name" bean property
+    // It must be public!
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/TemplateConfigurationExamples.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/TemplateConfigurationExamples.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/TemplateConfigurationExamples.java
new file mode 100644
index 0000000..3ea518d
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/TemplateConfigurationExamples.java
@@ -0,0 +1,191 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import static org.junit.Assert.*;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Date;
+
+import org.apache.freemarker.core.Configuration;
+import org.apache.freemarker.core.Template;
+import org.apache.freemarker.core.TemplateConfiguration;
+import org.apache.freemarker.core.outputformat.impl.HTMLOutputFormat;
+import org.apache.freemarker.core.outputformat.impl.PlainTextOutputFormat;
+import org.apache.freemarker.core.outputformat.impl.UndefinedOutputFormat;
+import org.apache.freemarker.core.outputformat.impl.XMLOutputFormat;
+import org.apache.freemarker.core.templateresolver.ConditionalTemplateConfigurationFactory;
+import org.apache.freemarker.core.templateresolver.FileExtensionMatcher;
+import org.apache.freemarker.core.templateresolver.FileNameGlobMatcher;
+import org.apache.freemarker.core.templateresolver.FirstMatchTemplateConfigurationFactory;
+import org.apache.freemarker.core.templateresolver.MergingTemplateConfigurationFactory;
+import org.apache.freemarker.core.templateresolver.OrMatcher;
+import org.apache.freemarker.core.templateresolver.PathGlobMatcher;
+import org.apache.freemarker.core.util._DateUtil;
+import org.apache.freemarker.test.TemplateTest;
+import org.apache.freemarker.test.TestConfigurationBuilder;
+import org.junit.Test;
+
+public class TemplateConfigurationExamples extends TemplateTest {
+
+    @Test
+    public void example1JavaCfg() throws Exception {
+        example1(true);
+    }
+
+    @Test
+    public void example1PropertiesCfg() throws Exception {
+        example1(false);
+    }
+
+    private void example1(boolean javaCfg) throws Exception {
+        TestConfigurationBuilder cfgB = new TestConfigurationBuilder(this.getClass());
+        if (javaCfg) {
+            cfgB.setTemplateConfigurations(new ConditionalTemplateConfigurationFactory(
+                    new FileExtensionMatcher("xml"),
+                    new TemplateConfiguration.Builder()
+                            .sourceEncoding(StandardCharsets.UTF_8)
+                            .outputFormat(XMLOutputFormat.INSTANCE)
+                            .build()));
+
+        } else {
+            cfgB.setTemplateConfigurations(null);
+            cfgB.setSettings(loadPropertiesFile("TemplateConfigurationExamples1.properties"));
+        }
+        setConfiguration(cfgB.build());
+
+        addTemplate("t.xml", "");
+
+        Template t = getConfiguration().getTemplate("t.xml");
+        assertEquals(StandardCharsets.UTF_8, t.getActualSourceEncoding());
+        assertEquals(XMLOutputFormat.INSTANCE, t.getOutputFormat());
+    }
+
+    @Test
+    public void example2JavaCfg() throws Exception {
+        example2(true);
+    }
+
+    @Test
+    public void example2PropertiesCfg() throws Exception {
+        example2(false);
+    }
+
+    private void example2(boolean javaCfg) throws Exception {
+        TestConfigurationBuilder cfgB = new TestConfigurationBuilder(this.getClass());
+        if (javaCfg) {
+            cfgB.setTemplateConfigurations(
+                    new ConditionalTemplateConfigurationFactory(
+                            new PathGlobMatcher("mail/**"),
+                            new FirstMatchTemplateConfigurationFactory(
+                                    new ConditionalTemplateConfigurationFactory(
+                                            new FileNameGlobMatcher("*.subject.*"),
+                                            new TemplateConfiguration.Builder()
+                                                    .outputFormat(PlainTextOutputFormat.INSTANCE)
+                                                    .build()),
+                                    new ConditionalTemplateConfigurationFactory(
+                                            new FileNameGlobMatcher("*.body.*"),
+                                            new TemplateConfiguration.Builder()
+                                                    .outputFormat(HTMLOutputFormat.INSTANCE)
+                                                    .build())
+                            )
+                            .noMatchErrorDetails(
+                                    "Mail template names must contain \".subject.\" or \".body.\"!")));
+        } else{
+            cfgB.setSettings(loadPropertiesFile("TemplateConfigurationExamples2.properties"));
+        }
+        setConfiguration(cfgB.build());
+
+        addTemplate("t.subject.ftl", "");
+        addTemplate("mail/t.subject.ftl", "");
+        addTemplate("mail/t.body.ftl", "");
+
+        Configuration cfg = getConfiguration();
+        assertEquals(UndefinedOutputFormat.INSTANCE, cfg.getTemplate("t.subject.ftl").getOutputFormat());
+        assertEquals(PlainTextOutputFormat.INSTANCE, cfg.getTemplate("mail/t.subject.ftl").getOutputFormat());
+        assertEquals(HTMLOutputFormat.INSTANCE, cfg.getTemplate("mail/t.body.ftl").getOutputFormat());
+    }
+
+    @Test
+    public void example3JavaCfg() throws Exception {
+        example3(true);
+    }
+
+    @Test
+    public void example3PropertiesCfg() throws Exception {
+        example3(false);
+    }
+
+    private void example3(boolean javaCfg) throws Exception {
+        TestConfigurationBuilder cfgB = new TestConfigurationBuilder(this.getClass())
+                .sourceEncoding(StandardCharsets.ISO_8859_1);
+        if (javaCfg) {
+            cfgB.setTemplateConfigurations(
+                    new MergingTemplateConfigurationFactory(
+                            new ConditionalTemplateConfigurationFactory(
+                                    new FileNameGlobMatcher("*.stats.*"),
+                                    new TemplateConfiguration.Builder()
+                                            .dateTimeFormat("iso")
+                                            .dateFormat("iso")
+                                            .timeFormat("iso")
+                                            .timeZone(_DateUtil.UTC)
+                                            .build()),
+                            new ConditionalTemplateConfigurationFactory(
+                                    new PathGlobMatcher("mail/**"),
+                                    new TemplateConfiguration.Builder()
+                                            .sourceEncoding(StandardCharsets.UTF_8)
+                                            .build()),
+                            new FirstMatchTemplateConfigurationFactory(
+                                    new ConditionalTemplateConfigurationFactory(
+                                            new FileExtensionMatcher("xml"),
+                                            new TemplateConfiguration.Builder()
+                                                    .outputFormat(XMLOutputFormat.INSTANCE)
+                                                    .build()),
+                                    new ConditionalTemplateConfigurationFactory(
+                                            new OrMatcher(
+                                                    new FileExtensionMatcher("html"),
+                                                    new FileExtensionMatcher("htm")),
+                                            new TemplateConfiguration.Builder()
+                                                    .outputFormat(HTMLOutputFormat.INSTANCE)
+                                                    .build())
+                            ).allowNoMatch(true)));
+        } else {
+            cfgB.setSettings(loadPropertiesFile("TemplateConfigurationExamples3.properties"));
+        }
+        setConfiguration(cfgB.build());
+
+        addTemplate("t.stats.html", "${ts?datetime} ${ts?date} ${ts?time}");
+        addTemplate("t.html", "");
+        addTemplate("t.htm", "");
+        addTemplate("t.xml", "");
+        addTemplate("mail/t.html", "");
+
+        addToDataModel("ts", new Date(1440431606011L));
+
+        Configuration cfg = getConfiguration();
+        assertEquals(HTMLOutputFormat.INSTANCE, cfg.getTemplate("t.html").getOutputFormat());
+        assertEquals(StandardCharsets.ISO_8859_1, cfg.getTemplate("t.html").getActualSourceEncoding());
+        assertEquals(HTMLOutputFormat.INSTANCE, cfg.getTemplate("t.htm").getOutputFormat());
+        assertEquals(XMLOutputFormat.INSTANCE, cfg.getTemplate("t.xml").getOutputFormat());
+        assertEquals(HTMLOutputFormat.INSTANCE, cfg.getTemplate("t.stats.html").getOutputFormat());
+        assertOutputForNamed("t.stats.html", "2015-08-24T15:53:26.011Z 2015-08-24 15:53:26.011Z");
+        assertEquals(StandardCharsets.UTF_8, cfg.getTemplate("mail/t.html").getActualSourceEncoding());
+    }
+    
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberFormatFactory.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberFormatFactory.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberFormatFactory.java
new file mode 100644
index 0000000..2b50654
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberFormatFactory.java
@@ -0,0 +1,80 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import java.util.Locale;
+
+import org.apache.freemarker.core.Environment;
+import org.apache.freemarker.core.model.TemplateModelException;
+import org.apache.freemarker.core.model.TemplateNumberModel;
+import org.apache.freemarker.core.valueformat.TemplateNumberFormat;
+import org.apache.freemarker.core.valueformat.TemplateNumberFormatFactory;
+import org.apache.freemarker.core.valueformat.TemplateValueFormatException;
+
+/**
+ * A number format that takes any other number format as parameter (specified as a string, as
+ * usual in FreeMarker), then if the model is a {@link UnitAwareTemplateNumberModel}, it  shows
+ * the unit after the number formatted with the other format, otherwise it just shows the formatted
+ * number without unit.
+ */
+public class UnitAwareTemplateNumberFormatFactory extends TemplateNumberFormatFactory {
+
+    public static final UnitAwareTemplateNumberFormatFactory INSTANCE
+            = new UnitAwareTemplateNumberFormatFactory();
+
+    private UnitAwareTemplateNumberFormatFactory() {
+        // Defined to decrease visibility
+    }
+
+    @Override
+    public TemplateNumberFormat get(String params, Locale locale, Environment env)
+            throws TemplateValueFormatException {
+        return new UnitAwareNumberFormat(env.getTemplateNumberFormat(params, locale));
+    }
+
+    private static class UnitAwareNumberFormat extends TemplateNumberFormat {
+
+        private final TemplateNumberFormat innerFormat;
+
+        private UnitAwareNumberFormat(TemplateNumberFormat innerFormat) {
+            this.innerFormat = innerFormat;
+        }
+
+        @Override
+        public String formatToPlainText(TemplateNumberModel numberModel)
+                throws TemplateModelException, TemplateValueFormatException {
+            String innerResult = innerFormat.formatToPlainText(numberModel);
+            return numberModel instanceof UnitAwareTemplateNumberModel
+                    ? innerResult + " " + ((UnitAwareTemplateNumberModel) numberModel).getUnit()
+                    : innerResult;
+        }
+
+        @Override
+        public boolean isLocaleBound() {
+            return innerFormat.isLocaleBound();
+        }
+
+        @Override
+        public String getDescription() {
+            return "unit-aware " + innerFormat.getDescription();
+        }
+
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberModel.java
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberModel.java b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberModel.java
new file mode 100644
index 0000000..65105c6
--- /dev/null
+++ b/freemarker-manual/src/test/java/org/apache/freemarker/manual/examples/UnitAwareTemplateNumberModel.java
@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+package org.apache.freemarker.manual.examples;
+
+import org.apache.freemarker.core.model.TemplateModelException;
+import org.apache.freemarker.core.model.TemplateNumberModel;
+
+public class UnitAwareTemplateNumberModel implements TemplateNumberModel {
+
+    private final Number value;
+    private final String unit;
+    
+    public UnitAwareTemplateNumberModel(Number value, String unit) {
+        this.value = value;
+        this.unit = unit;
+    }
+
+    @Override
+    public Number getAsNumber() throws TemplateModelException {
+        return value;
+    }
+
+    public String getUnit() {
+        return unit;
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh
new file mode 100644
index 0000000..24bd0ee
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh
@@ -0,0 +1,21 @@
+<#--
+  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.
+-->
+<#assign captured><b>Test</b></#assign>
+Just a string: ${"<b>Test</b>"}
+Captured output: ${captured}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh.out
new file mode 100644
index 0000000..cf0da7e
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-capture.ftlh.out
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+Just a string: &lt;b&gt;Test&lt;/b&gt;
+Captured output: <b>Test</b>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh
new file mode 100644
index 0000000..e0d3348
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh
@@ -0,0 +1,27 @@
+<#--
+  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.
+-->
+<#assign mo1 = "Foo's bar {}"?esc>
+HTLM: ${mo1}
+XML:  <#outputformat 'XML'>${mo1}</#outputformat>
+RTF:  <#outputformat 'RTF'>${mo1}</#outputformat>
+
+<#assign mo2><p>Test</#assign>
+HTML: ${mo2}
+XML:  <#attempt><#outputformat 'XML'>${mo2}</#outputformat><#recover>Failed</#attempt>
+RTF:  <#attempt><#outputformat 'RTF'>${mo2}</#outputformat><#recover>Failed</#attempt>

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh.out
new file mode 100644
index 0000000..65be2a0
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert.ftlh.out
@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+HTLM: Foo&#39;s bar {}
+XML:  Foo&apos;s bar {}
+RTF:  Foo's bar \{\}
+
+HTML: <p>Test
+XML:  Failed
+RTF:  Failed

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl
new file mode 100644
index 0000000..80ae292
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl
@@ -0,0 +1,25 @@
+<#--
+  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.
+-->
+<#outputformat "HTML"><#assign htmlMO><p>Test</#assign></#outputformat>
+<#outputformat "XML"><#assign xmlMO><p>Test</p></#assign></#outputformat>
+<#outputformat "RTF"><#assign rtfMO>\par Test</#assign></#outputformat>
+<#-- We assume that we have "undefined" output format here. -->
+HTML: ${htmlMO}
+XML:  ${xmlMO}
+RTF:  ${rtfMO}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl.out
new file mode 100644
index 0000000..cd84bd2
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-convert2.ftl.out
@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+HTML: <p>Test
+XML:  <p>Test</p>
+RTF:  \par Test
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh
new file mode 100644
index 0000000..9b8dbd9
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh
@@ -0,0 +1,26 @@
+<#--
+  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.
+-->
+<@infoBox "Foo & bar" />
+<@infoBox "Foo <b>bar</b>"?no_esc />
+
+<#macro infoBox message>
+  <div class="infoBox">
+    ${message}
+  </div>
+</#macro>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh.out
new file mode 100644
index 0000000..9471ab7
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-infoBox.ftlh.out
@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+  <div class="infoBox">
+    Foo &amp; bar
+  </div>
+  <div class="infoBox">
+    Foo <b>bar</b>
+  </div>
+

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh
new file mode 100644
index 0000000..f9deeae
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh
@@ -0,0 +1,28 @@
+<#--
+  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.
+-->
+<#assign markupOutput1="<b>Test</b>"?no_esc>
+<#assign markupOutput2="Foo & bar"?esc>
+
+As expected:
+${markupOutput1}
+${markupOutput2}
+
+Double escaping:
+${markupOutput1?markup_string}
+${markupOutput2?markup_string}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh.out
new file mode 100644
index 0000000..0420cca
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-markup.ftlh.out
@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+As expected:
+<b>Test</b>
+Foo &amp; bar
+
+Double escaping:
+&lt;b&gt;Test&lt;/b&gt;
+Foo &amp;amp; bar
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh
new file mode 100644
index 0000000..f7884bb
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh
@@ -0,0 +1,19 @@
+<#--
+  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.
+-->
+${"<h1>"?no_esc + "Foo & bar" + "</h1>"?no_esc}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh.out
new file mode 100644
index 0000000..d016072
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringConcat.ftlh.out
@@ -0,0 +1,19 @@
+/*
+ * 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.
+ */
+<h1>Foo &amp; bar</h1>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh
new file mode 100644
index 0000000..4904f60
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh
@@ -0,0 +1,21 @@
+<#--
+  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.
+-->
+<#assign s = "Foo & bar">
+${s}
+${"${s} & baz"}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh.out
new file mode 100644
index 0000000..c6bd10d
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral.ftlh.out
@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+Foo &amp; bar
+Foo &amp; bar &amp; baz
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh
new file mode 100644
index 0000000..52db70b
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh
@@ -0,0 +1,25 @@
+<#--
+  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.
+-->
+<#-- Markup output value created by escaping plain text: -->
+<#assign mo1 = "Foo & bar"?esc>
+<#-- Markup output value created outherwise: -->
+<#assign mo2 = "<p>Foo"?no_esc>
+
+${"${mo1} baz"}
+${"${mo2} baz"}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh.out
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh.out b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh.out
new file mode 100644
index 0000000..f47e521
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/AutoEscapingExample-stringLiteral2.ftlh.out
@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+
+Foo &amp; bar baz
+<p>Foo baz
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/abfcac88/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples1.properties
----------------------------------------------------------------------
diff --git a/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples1.properties b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples1.properties
new file mode 100644
index 0000000..0df9e33
--- /dev/null
+++ b/freemarker-manual/src/test/resources/org/apache/freemarker/manual/examples/ConfigureOutputFormatExamples1.properties
@@ -0,0 +1,21 @@
+# 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.
+
+templateConfigurations = \
+    ConditionalTemplateConfigurationFactory( \
+        PathGlobMatcher("mail/**"), \
+        TemplateConfiguration(outputFormat = HTMLOutputFormat()))
\ No newline at end of file