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 2017/03/01 14:21:00 UTC
[02/50] [abbrv] incubator-freemarker git commit: Manual: Replaced
strange ``..." quotations with ...
. Fixed some minor typos
spotted during that.
Manual: Replaced strange ``..." quotations with <quote>...</quote>. Fixed some minor typos spotted during that.
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/bc202885
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/bc202885
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/bc202885
Branch: refs/heads/2.3
Commit: bc2028855f6af1e9d723d944cb7f323003458ac1
Parents: 8161349
Author: ddekany <dd...@apache.org>
Authored: Wed Jan 25 18:17:31 2017 +0100
Committer: ddekany <dd...@apache.org>
Committed: Wed Jan 25 18:17:31 2017 +0100
----------------------------------------------------------------------
src/manual/en_US/book.xml | 501 +++++++++++++++++++++--------------------
1 file changed, 259 insertions(+), 242 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/bc202885/src/manual/en_US/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index 38da320..3449535 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -1937,9 +1937,9 @@ The average of the price of a python and an elephant is:
interpolations is
<literal>${<replaceable>expression</replaceable>}</literal> where
expression gives the value you want to insert into the output as
- text. So <literal>${(5 + 8)/2}</literal> prints ``6.5'' to the
- output (or possibly ``6,5'' if the language of your output is not
- US English).</para>
+ text. So <literal>${(5 + 8)/2}</literal> prints <quote>6.5</quote>
+ to the output (or possibly <quote>6,5</quote> if the language of
+ your output is not US English).</para>
</listitem>
<listitem>
@@ -3398,7 +3398,7 @@ ${12 % -5} <#-- Prints 2 -->
(or <literal>=</literal> as a <emphasis>deprecated</emphasis>
alternative) To test two values for inequality you use
<literal>!=</literal>. For example, assume that
- <literal>user</literal> is ``Big Joe'':</para>
+ <literal>user</literal> is <quote>Big Joe</quote>:</para>
<programlisting role="template"><#if <emphasis>user == "Big Joe"</emphasis>>
It is Big Joe
@@ -3409,8 +3409,8 @@ ${12 % -5} <#-- Prints 2 -->
<para>The <literal>user == "Big Joe"</literal> expression in the
<literal><#if ...></literal> will evaluate to the boolean
- <literal>true</literal>, so the above will say ``It is Big
- Joe''.</para>
+ <literal>true</literal>, so the above will say <quote>It is Big
+ Joe</quote>.</para>
<para>The expressions on both sides of the <literal>==</literal> or
<literal>!=</literal> must evaluate to a scalar (not a sequence or
@@ -3577,7 +3577,7 @@ ${testSequence?size}
${testSequence?join(", ")}</programlisting>
<para>Assuming that <literal>testString</literal> stores the string
- ``Tom & Jerry'', and testSequnce stores the strings
+ <quote>Tom & Jerry</quote>, and testSequnce stores the strings
<quote>foo</quote>, <quote>bar</quote> and <quote>baz</quote>, the
output will be:</para>
@@ -3994,7 +3994,7 @@ ${("green " + "mouse")?upper_case} <#-- GREEN MOUSE -->
precedence. Operators with higher precedence are evaluated before
operators with a relatively lower precedence. Operators on the same
line have equal precedence. When binary operators (operators with
- two ``parameters'', as <literal>+</literal> and
+ two <quote>parameters</quote>, as <literal>+</literal> and
<literal>-</literal>) of equal precedence appear next to each other,
they are evaluated in left-to-right order.</para>
@@ -4397,7 +4397,7 @@ ${("green " + "mouse")?upper_case} <#-- GREEN MOUSE -->
<para>A macro is a template fragment associated with a variable. You
can use that variable in your template as a user-defined directive,
so it helps in repetitive tasks. For example, this creates a macro
- variable that prints a big ``Hello Joe!'':</para>
+ variable that prints a big <quote>Hello Joe!</quote>:</para>
<programlisting role="template"><emphasis><#macro greet></emphasis>
<font size="+2">Hello Joe!</font>
@@ -4451,8 +4451,8 @@ ${("green " + "mouse")?upper_case} <#-- GREEN MOUSE -->
<title>Parameters</title>
<para>Let's improve the <literal>greet</literal> macro so it can use
- arbitrary name, not only ``Joe''. For this purpose you can use
- <emphasis role="term">parameters</emphasis>. You define the
+ arbitrary name, not only <quote>Joe</quote>. For this purpose you
+ can use <emphasis role="term">parameters</emphasis>. You define the
parameters after the name of the macro in the
<literal>macro</literal> directive. Here we define one parameter for
the <literal>greet</literal> macro,
@@ -11142,19 +11142,20 @@ TemplateHashModel roundingModeEnums =
<para>But, probably you want to use FreeMarker with some already
existing Web application framework. Many frameworks rely on the
- ``Model 2'' architecture, where JSP pages handle presentation. If you
- use such a framework (for example, <link
+ <quote>Model 2</quote> architecture, where JSP pages handle
+ presentation. If you use such a framework (for example, <link
xlink:href="http://jakarta.apache.org/struts">Apache Struts</link>),
then read on. For other frameworks please refer to the documentation
of the framework.</para>
<section xml:id="pgui_misc_servlet_model2">
- <title>Using FreeMarker for ``Model 2''</title>
+ <title>Using FreeMarker for <quote>Model 2</quote></title>
<para>Many frameworks follow the strategy that the HTTP request is
- dispatched to user-defined ``action'' classes that put data into
- <literal>ServletContext</literal>, <literal>HttpSession</literal>
- and <literal>HttpServletRequest</literal> objects as attributes, and
+ dispatched to user-defined <quote>action</quote> classes that put
+ data into <literal>ServletContext</literal>,
+ <literal>HttpSession</literal> and
+ <literal>HttpServletRequest</literal> objects as attributes, and
then the request is forwarded by the framework to a JSP page (the
view) that will generate the HTML page using the data sent with the
attributes. This is often referred as Model 2.</para>
@@ -11642,15 +11643,16 @@ ${bar?trim}</programlisting>
</note>
<para>Since JSP custom tags are written to operate in JSP
- environment, they assume that variables (often referred as ``beans''
- in JSP world) are stored in 4 scopes: page scope, request scope,
- session scope and application scope. FTL has no such notation (the 4
- scopes), but <literal>FreemarkerServlet</literal> provides emulated
- JSP environment for the custom JSP tags, which maintains
- correspondence between the ``beans'' of JSP scopes and FTL
- variables. For the custom JSP tags, the request, session and
- application scopes are exactly the same as with real JSP: the
- attributes of the <literal>javax.servlet.ServletContext</literal>,
+ environment, they assume that variables (often referred as
+ <quote>beans</quote> in JSP world) are stored in 4 scopes: page
+ scope, request scope, session scope and application scope. FTL has
+ no such notation (the 4 scopes), but
+ <literal>FreemarkerServlet</literal> provides emulated JSP
+ environment for the custom JSP tags, which maintains correspondence
+ between the <quote>beans</quote> of JSP scopes and FTL variables.
+ For the custom JSP tags, the request, session and application scopes
+ are exactly the same as with real JSP: the attributes of the
+ <literal>javax.servlet.ServletContext</literal>,
<literal>HttpSession</literal> and <literal>ServletRequest</literal>
objects. From the FTL side you see these 3 scopes together as the
data-model, as it was explained earlier. The page scope corresponds
@@ -11672,9 +11674,10 @@ ${bar?trim}</programlisting>
since custom tags are accessible in FTL templates as user-defined
FTL directives, you have to use the FTL syntax rules inside the
custom tags, not the JSP rules. So when you specify the value of an
- ``attribute'', then on the right side of the <literal>=</literal>
- there is an <link linkend="dgui_template_exp">FTL expression</link>.
- Thus, <emphasis>you must not quote boolean and numerical parameter
+ <quote>attribute</quote>, then on the right side of the
+ <literal>=</literal> there is an <link
+ linkend="dgui_template_exp">FTL expression</link>. Thus,
+ <emphasis>you must not quote boolean and numerical parameter
values</emphasis> (e.g. <literal><@tiles.insert
page="/layout.ftl" flush=true/></literal>), or they are
interpreted as string values, and this will cause a type mismatch
@@ -12157,7 +12160,7 @@ grant codeBase "file:/path/to/freemarker.jar"
<primary>ant task</primary>
</indexterm>
- <para>There are two ``FreeMarker Ant tasks'' that we know
+ <para>There are two <quote>FreeMarker Ant tasks</quote> that we know
about:</para>
<itemizedlist>
@@ -12905,7 +12908,7 @@ grant codeBase "file:/path/to/freemarker.jar"
</indexterm>
<para>The string with the very first word of the string capitalized.
- For the precise meaning of ``word'' see the <link
+ For the precise meaning of <quote>word</quote> see the <link
linkend="ref_builtin_word_list">word_list built-in</link>.
Example:</para>
@@ -12931,8 +12934,9 @@ GreEN mouse
</indexterm>
<para>The string with all words capitalized. For the precise meaning
- of ``word'' see the <link linkend="ref_builtin_word_list">word_list
- built-in</link>. Example:</para>
+ of <quote>word</quote> see the <link
+ linkend="ref_builtin_word_list">word_list built-in</link>.
+ Example:</para>
<programlisting role="template">${" green mouse"?capitalize}
${"GreEN mouse"?capitalize}</programlisting>
@@ -13775,8 +13779,8 @@ String BEAN_NAME = "${beanName?j_string}";</programlisting>
<primary>matches built-in</primary>
</indexterm>
- <para>This is a ``power user'' built-in. Ignore it if you don't know
- <link linkend="gloss.regularExpression">regular
+ <para>This is a <quote>power user</quote> built-in. Ignore it if you
+ don't know <link linkend="gloss.regularExpression">regular
expressions</link>.</para>
<para>This built-in determines if the string exactly matches the
@@ -14705,11 +14709,11 @@ ${x?url}</programlisting>
<title>Common flags</title>
<para>Many string built-ins accept an optional string parameter, the
- so called ``flags''. In this string, each letter influences a
- certain aspect of the behavior of the built-in. For example, letter
- <literal>i</literal> means that the built-in should not
- differentiate the lower and upper-case variation of the same letter.
- The order of the letters in the flags string is not
+ so called <quote>flags</quote>. In this string, each letter
+ influences a certain aspect of the behavior of the built-in. For
+ example, letter <literal>i</literal> means that the built-in should
+ not differentiate the lower and upper-case variation of the same
+ letter. The order of the letters in the flags string is not
significant.</para>
<para>This is the complete list of letters (flags):</para>
@@ -15020,8 +15024,8 @@ rif: foo XYr baar</programlisting>
<literal>${x}</literal>), or else the output will be possibly broken
depending on the current number formatting settings and locale (like
the decimal point is not dot, but comma in many countries) and the
- value of the number (like big numbers are possibly ``damaged'' by
- grouping separators).</para>
+ value of the number (like big numbers are possibly
+ <quote>damaged</quote> by grouping separators).</para>
<para>If the <literal>incompatible_imporvements</literal> FreeMarker
configuration setting is set to 2.3.24 or higher (also if it's set
@@ -16410,8 +16414,8 @@ N
<para>This built in is mostly for outputting sequnces in
tabular/columnar format. When used with HTML tables, the 2nd
parameter is often <literal>"\xA0"</literal> (that is the code of
- the no-break space character, also known as ``nbsp''), so the border
- of the empty TD-s will not be missing.</para>
+ the no-break space character, also known as <quote>nbsp</quote>), so
+ the border of the empty TD-s will not be missing.</para>
<para>The 1st parameter must be a number that is at least 1. If the
number is not integer, it will be silently rounded down to integer
@@ -16975,8 +16979,9 @@ Sorted by name.last:
</indexterm>
<para>Returns the string that is used to determine what user-defined
- directive to invoke to handle this node when it is ``visited''. See:
- the <link linkend="ref.directive.visit">visit</link> and <link
+ directive to invoke to handle this node when it is
+ <quote>visited</quote>. See: the <link
+ linkend="ref.directive.visit">visit</link> and <link
linkend="ref.directive.recurse">recurse</link> directives.</para>
<para>XML: If the node is an element or attribute, then the string
@@ -17134,12 +17139,12 @@ Sorted by name.last:
<para>XML: According to W3C, the root of an XML document is not the
topmost element node, but the document itself, which is the parent
of the topmost element. For example, if you want to get the topmost
- <emphasis>element</emphasis> of the XML (the so called ``document
- element''; do not mix it with the ``document''), which is called
- <literal>foo</literal>, then you have to write
- <literal>someNode?root.foo</literal>. If you write just
- <literal>someNode?root</literal>, then you get the document itself,
- and not the document element.</para>
+ <emphasis>element</emphasis> of the XML (the so called
+ <quote>document element</quote>; do not mix it with the
+ <quote>document</quote>), which is called <literal>foo</literal>,
+ then you have to write <literal>someNode?root.foo</literal>. If you
+ write just <literal>someNode?root</literal>, then you get the
+ document itself, and not the document element.</para>
</section>
</section>
@@ -18234,9 +18239,10 @@ Sorted by name.last:
<primary>namespace built-in</primary>
</indexterm>
- <para>This built-in returns the namespace (i.e. the ``gate'' hash to
- the namespace) associated with a macro or function variable. You can
- use it with macros and functions only.</para>
+ <para>This built-in returns the namespace (i.e. the
+ <quote>gate</quote> hash to the namespace) associated with a macro
+ or function variable. You can use it with macros and functions
+ only.</para>
</section>
<section xml:id="ref_builtin_new">
@@ -18801,12 +18807,12 @@ Primary content continued</programlisting>
or no output at all results from the execution of the
<literal><replaceable>attempt block</replaceable></literal> (when
there was an error). For example, above, the failure happens after
- ``Optional content: '' was printed, still it is not there in the
- output before the ``Ops!''. (<phrase role="forProgrammers">This is
- implemented with the aggressive buffering of the output inside the
- <literal><replaceable>attempt block</replaceable></literal>. Not
- even the <literal>flush</literal> directive will send the output to
- the client.</phrase>)</para>
+ <quote>Optional content: </quote> was printed, still it is not there
+ in the output before the <quote>Ops!</quote>. (<phrase
+ role="forProgrammers">This is implemented with the aggressive
+ buffering of the output inside the <literal><replaceable>attempt
+ block</replaceable></literal>. Not even the <literal>flush</literal>
+ directive will send the output to the client.</phrase>)</para>
<para>To prevent misunderstandings coming from the above example:
<literal>attempt</literal>/<literal>recover</literal> is not (only)
@@ -19368,11 +19374,11 @@ m2: &lt;test&gt;</programlisting>
an FTL namespace is created for the template that contains it,
otherwise the <literal>ns_prefixes</literal> parameter has no
effect. An FTL namespace is made for a template when: (a) the
- template is the ``main'' template, that is, it is not invoked as
- a result of an <literal><#include ...></literal>, but it
- is directly invoked (<phrase role="forProgrammers">with the
- <literal>process</literal> Java method of class
- <literal>Template</literal> or
+ template is the <quote>main</quote> template, that is, it is not
+ invoked as a result of an <literal><#include
+ ...></literal>, but it is directly invoked (<phrase
+ role="forProgrammers">with the <literal>process</literal> Java
+ method of class <literal>Template</literal> or
<literal>Environment</literal></phrase>); (b) the template is
invoked directly with <literal><#import
...></literal>.</para>
@@ -19401,18 +19407,15 @@ m2: &lt;test&gt;</programlisting>
<listitem>
<para><literal>strict_syntax</literal>: This turns on/off
- ``strict syntax''. Valid values are the boolean constants
+ <quote>strict syntax</quote>, which is the standard syntax after
+ FreeMarker 2.1. Valid values are the boolean constants
<literal>true</literal> and <literal>false</literal>. (And for
backward compatibility, strings <literal>"yes"</literal>,
<literal>"no"</literal>, <literal>"true"</literal>,
- <literal>"false"</literal>). The default value (i.e. when you
+ <literal>"false"</literal>). The default value (i.e., when you
don't use this parameter) depends on the FreeMarker
- configuration set by the programmers, but it should be
- <literal>true</literal> for new projects. <phrase
- role="forProgrammers">(Programmers: you must set explicitly this
- setting to <literal>true</literal> for this:
- <literal>config.setStrictSyntaxMode(true);</literal>)</phrase>
- For more information read: <xref
+ configuration set by the programmers, but it's most certainly
+ set to <literal>true</literal>. For more information read: <xref
linkend="ref_depr_oldsyntax"/></para>
</listitem>
@@ -22247,16 +22250,16 @@ or
<itemizedlist>
<listitem>
- <para>``leading white-space'' means all space and tab (and other
- character that are white-space according to <link
+ <para><quote>leading white-space</quote> means all space and tab
+ (and other character that are white-space according to <link
linkend="gloss.unicode">UNICODE</link>, except <link
linkend="gloss.lineBreak">line breaks</link>) before the first
non-white-space character of the line.</para>
</listitem>
<listitem>
- <para>``trailing white-space'' means all space and tab (and
- other character that are white-space according to <link
+ <para><quote>trailing white-space</quote> means all space and
+ tab (and other character that are white-space according to <link
linkend="gloss.unicode">UNICODE</link>, except line breaks)
after the last non-white-space character of the line,
<emphasis>and</emphasis> the line break at the end of the
@@ -23139,31 +23142,33 @@ There was no specific handler for node y
<itemizedlist spacing="compact">
<listitem>
- <para><literal>true</literal>: boolean value ``true''</para>
+ <para><literal>true</literal>: boolean value
+ <quote>true</quote></para>
</listitem>
<listitem>
- <para><literal>false</literal>: boolean value ``false''</para>
+ <para><literal>false</literal>: boolean value
+ <quote>false</quote></para>
</listitem>
<listitem>
- <para><literal>gt</literal>: comparison operator ``greater
- than''</para>
+ <para><literal>gt</literal>: comparison operator <quote>greater
+ than</quote></para>
</listitem>
<listitem>
- <para><literal>gte</literal>: comparison operator ``greater than or
- equivalent''</para>
+ <para><literal>gte</literal>: comparison operator <quote>greater
+ than or equivalent</quote></para>
</listitem>
<listitem>
- <para><literal>lt</literal>: comparison operator ``less
- than''</para>
+ <para><literal>lt</literal>: comparison operator <quote>less
+ than</quote></para>
</listitem>
<listitem>
- <para><literal>lte</literal>: comparison operator ``less than or
- equivalent''</para>
+ <para><literal>lte</literal>: comparison operator <quote>less than
+ or equivalent</quote></para>
</listitem>
<listitem>
@@ -23530,7 +23535,7 @@ or
<para>Some transforms may take parameters. The name and meaning of
parameters depends on the transform in question. For example here we
- give a parameter called ``var'':</para>
+ give a parameter called <quote>var</quote>:</para>
<programlisting role="template"><#-- This transform stores the output in the variable x,
rather than sending it to the output -->
@@ -23587,12 +23592,13 @@ some test
<para>While the <literal>#</literal>-less syntax was more natural for
HTML authors, it had too many drawbacks, so finally we have decided to
- deprecate it. With the newer syntax (a.k.a ``strict syntax''), the
- <literal>#</literal> is strictly required. That is, things like
- <literal><include "common_footer.html"></literal> will go to the
- output as is, since they are not considered as FTL tags. Note that
- user-defined directives use <literal>@</literal> <emphasis>instead
- of</emphasis> <literal>#</literal>.</para>
+ deprecate it. With the newer syntax (a.k.a <quote>strict
+ syntax</quote>), the <literal>#</literal> is strictly required. That
+ is, things like <literal><include
+ "common_footer.html"></literal> will go to the output as is, since
+ they are not considered as FTL tags. Note that user-defined directives
+ use <literal>@</literal> <emphasis>instead of</emphasis>
+ <literal>#</literal>.</para>
<para>However, to give users time to prepare for this change, in
FreeMarker 2.1 and 2.2 the usage of <literal>#</literal> is optional,
@@ -23606,8 +23612,8 @@ some test
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link>.</para>
- <para>The advantages of ``strict syntax'' over the legacy FTL syntax
- are:</para>
+ <para>The advantages of <quote>strict syntax</quote> over the legacy
+ FTL syntax are:</para>
<itemizedlist>
<listitem>
@@ -23770,11 +23776,11 @@ or
cases. Also its syntax is terribly verbose. However, XSLT's
"apply-templates" method can be very handy when you process XML
documents, thus FreeMarker supports something similar called the
- ``visitor pattern''. So in many applications, it is much easier to write
- FTL stylesheets than XSLT style-sheets. Another fundamental difference
- is that FTL "transforms" the node tree to text, while XSLT transforms
- the tree to another tree. So you cannot always use FreeMarker where you
- can use XSLT.</para>
+ <quote>visitor pattern</quote>. So in many applications, it is much
+ easier to write FTL stylesheets than XSLT style-sheets. Another
+ fundamental difference is that FTL "transforms" the node tree to text,
+ while XSLT transforms the tree to another tree. So you cannot always use
+ FreeMarker where you can use XSLT.</para>
</preface>
<chapter xml:id="xgui_expose">
@@ -23880,8 +23886,8 @@ or
<listitem>
<para>The topmost node of a tree is called the <emphasis
role="term">root</emphasis>. In the case of XML documents, it is
- always the ``document'' node, and not the top-most element
- (<literal>book</literal> in this example).</para>
+ always the <quote>document</quote> node, and not the top-most
+ element (<literal>book</literal> in this example).</para>
</listitem>
<listitem>
@@ -23941,7 +23947,7 @@ or
</note>
<para>It's easy to create a simple program to try the examples. Just
- replace the ``Create a data-model'' part of <link
+ replace the <quote>Create a data-model</quote> part of <link
linkend="pgui_quickstart_all">the example of Programmer's Guide
Quickstart</link> with this:</para>
@@ -23999,10 +24005,10 @@ root.put(
<para>Assume that the programmer has put the XML document into the
data-model as variable <literal>doc</literal>. This variable
corresponds to the root of the <link linkend="xgui_expose_dom">DOM
- tree</link>, the ``document''. The actual variable structure behind
- <literal>doc</literal> is wily enough, and only roughly resembles the
- DOM tree. So instead of getting lost in the details, let's see how to
- use it by example.</para>
+ tree</link>, the <quote>document</quote>. The actual variable
+ structure behind <literal>doc</literal> is wily enough, and only
+ roughly resembles the DOM tree. So instead of getting lost in the
+ details, let's see how to use it by example.</para>
<section>
<title>Accessing elements by name</title>
@@ -24124,9 +24130,9 @@ root.put(
</#list>
</#list></programlisting>
- <para>Finally, a ``generalized`` usage of the child selector
- mechanism: this template lists all <literal>para</literal>-s of the
- example XML document:</para>
+ <para>Finally, a generalized usage of the child selector mechanism:
+ this template lists all <literal>para</literal>-s of the example XML
+ document:</para>
<programlisting role="template"><#list doc.book.chapter.para as p>
<p>${p}
@@ -24362,7 +24368,7 @@ Test Book</programlisting>
sections) stands for XPath results as well. That is, if the
resulting sequence contains exactly 1 node, it also acts as the node
itself. For example, print the first paragraph of chapter
- ``Ch1'':</para>
+ <quote>Ch1</quote>:</para>
<programlisting role="template">${doc["book/chapter[title='Ch1']/para[1]"]}</programlisting>
@@ -24704,10 +24710,11 @@ Test Book</programlisting>
<literal>"<replaceable>prefix</replaceable>:<replaceable>elementName</replaceable>"</literal>:
Returns the sequence of child nodes that are elements of name
<literal><replaceable>elementName</replaceable></literal>. (Note
- that the term ``child'' means <emphasis>immediate</emphasis>
- descendant.) The selection is XML name-space aware, unless the XML
- document was persed with an XML parser that was not in namespace
- aware mode. In XML name-space aware mode, names without prefix
+ that the term <quote>child</quote> means
+ <emphasis>immediate</emphasis> descendant.) The selection is XML
+ name-space aware, unless the XML document was persed with an XML
+ parser that was not in namespace aware mode. In XML name-space
+ aware mode, names without prefix
(<replaceable>elementName</replaceable>) selects only elements
that doesn't belong to any XML name-space (unless you have
registered a default XML namespace), and names with prefix
@@ -24723,10 +24730,10 @@ Test Book</programlisting>
<listitem>
<para><literal>*</literal>: Returns the sequence of all child
(direct descendant) <emphasis>element</emphasis> nodes. The
- sequence will contain the elements in the ``document order'', that
- is, in the order in which the first character of the XML
- representation of each node occurs (after expansion of general
- entities).</para>
+ sequence will contain the elements in the <quote>document
+ order</quote>, that is, in the order in which the first character
+ of the XML representation of each node occurs (after expansion of
+ general entities).</para>
</listitem>
<listitem>
@@ -25009,14 +25016,14 @@ Test Book</programlisting>
is the <link
linkend="ref.directive.recurse"><literal>recurse</literal>
directive</link>. This directive gets a node variable as parameter,
- and ``visits'' all its children nodes, one after the other, starting
- with the first child. ``Visiting'' a node means that it calls a
- user-defined directive (like a macro) that has the same name as the
- name of the child node (<literal>?node_name</literal>). We say on
- this, that the user-defined directive <emphasis>handles</emphasis> the
- node. The node that the user-defined directive just handles is
- available as special variable <literal>.node</literal>. For example,
- this FTL:</para>
+ and <quote>visits</quote> all its children nodes, one after the other,
+ starting with the first child. <quote>Visiting</quote> a node means
+ that it calls a user-defined directive (like a macro) that has the
+ same name as the name of the child node
+ (<literal>?node_name</literal>). We say on this, that the user-defined
+ directive <emphasis>handles</emphasis> the node. The node that the
+ user-defined directive just handles is available as special variable
+ <literal>.node</literal>. For example, this FTL:</para>
<programlisting role="template"><#recurse doc>
@@ -25444,11 +25451,11 @@ End book</programlisting>
</listitem>
<listitem>
- <para>``Object wrapping''. This lets you show the objects to
- templates in a customized, presentation oriented way (e.g.
- <link linkend="xgui_imperative_learn">see here</link> how a
- W3C DOM nodes can be seen by templates using this
- technology.)</para>
+ <para><quote>Object wrapping</quote>. This lets you show the
+ objects to templates in a customized, presentation oriented
+ way (e.g. <link linkend="xgui_imperative_learn">see
+ here</link> how a W3C DOM nodes can be seen by templates using
+ this technology.)</para>
</listitem>
<listitem>
@@ -25468,11 +25475,12 @@ End book</programlisting>
<itemizedlist>
<listitem>
- <para>Not a ``standard''. There are fewer tools and IDE
- integrations, fewer developers knows it and there's much less
- industry support in general. (However, most JSP tag libraries
- can work in FreeMarker templates with the proper setup, unless
- they are base on <literal>.tag</literal> files.)</para>
+ <para>Not a <quote>standard</quote>. There are fewer tools and
+ IDE integrations, fewer developers knows it and there's much
+ less industry support in general. (However, most JSP tag
+ libraries can work in FreeMarker templates with the proper
+ setup, unless they are base on <literal>.tag</literal>
+ files.)</para>
</listitem>
<listitem>
@@ -25639,7 +25647,7 @@ End book</programlisting>
<programlisting role="template"><a href="/shop/productdetails?id=${<emphasis>product.id?c</emphasis>}">Details...</a></programlisting>
<para>For computer audience you need <literal>?c</literal> anyway,
- as the decimal separators can also warry depending on the
+ as the decimal separators can also wary depending on the
locale.</para>
</answer>
</qandaentry>
@@ -25662,10 +25670,10 @@ End book</programlisting>
// where cfg is a freemarker.template.Configuration object</programlisting>
<para>However, sometimes you want to output a number not for human
- audience, but for ``computer audience'' (like you want to print a
- size in CSS), in which case you must use dot as decimal separator,
- regardless of the locale (language) of the page. For that use the
- <link linkend="ref_builtin_c"><literal>c</literal>
+ audience, but for <quote>computer audience</quote> (like you want
+ to print a size in CSS), in which case you must use dot as decimal
+ separator, regardless of the locale (language) of the page. For
+ that use the <link linkend="ref_builtin_c"><literal>c</literal>
built-in</link>, for example:</para>
<programlisting role="template">font-size: ${<emphasis>fontSize?c</emphasis>}pt;</programlisting>
@@ -25733,7 +25741,7 @@ End book</programlisting>
</question>
<answer>
- <para>Firs of all, you should know that FreeMarker doesn't load
+ <para>First of all, you should know that FreeMarker doesn't load
templates from file system paths directly. Instead, it uses a
simple virtual file system that might reads non-filesystem
resources (templates from inside jar-s, from inside a database
@@ -25827,8 +25835,8 @@ End book</programlisting>
there is an older version of <literal>freemarker.jar</literal>
around, which shadows the never. To check this, try to print the
version number in a template with <literal>${.version}</literal>.
- (If it dies with ``Unknown built-in variable: version'' error
- message, then you use a very, very old release.).</para>
+ (If it dies with <quote>Unknown built-in variable: version</quote>
+ error message, then you use a very, very old release.).</para>
<para>If you suspect that the problem is that you have multiple
<literal>freemarker.jar</literal>-s, the typical culprit is that
@@ -26067,8 +26075,8 @@ End book</programlisting>
<itemizedlist>
<listitem>
<para>Directives and methods that are written for presentation
- purposes (like kind of ``tools'' for helping FreeMarker
- templates) should declare their arguments as
+ purposes (like kind of <quote>tools</quote> for helping
+ FreeMarker templates) should declare their arguments as
<literal>TemplateModel</literal>-s and the more specific sub
interfaces of that. After all, the object wrapping is about
transforming the data-model to something that serves the
@@ -26355,11 +26363,11 @@ End book</programlisting>
<literal>null</literal>, it treats it exactly as a missing
variable. For example, both if <literal>x</literal> is
<literal>null</literal> in the data-model and if it's not present
- at all, <literal>${x!'missing'}</literal> will print ``missing'',
- you can't tell the difference. Also, if for example you want to
- test if a Java method has returned <literal>null</literal>, just
- write something like <literal><#if
- foo.bar()??></literal>.</para>
+ at all, <literal>${x!'missing'}</literal> will print
+ <quote>missing</quote>, you can't tell the difference. Also, if
+ for example you want to test if a Java method has returned
+ <literal>null</literal>, just write something like
+ <literal><#if foo.bar()??></literal>.</para>
<para>You may interested in the rationale behind this. From the
viewpoint of the presentation layer a <literal>null</literal> and
@@ -26391,7 +26399,7 @@ End book</programlisting>
to the method instead. Like <literal>foo.bar(nullArg)</literal>
will call the <literal>bar</literal> method with
<literal>null</literal> as argument, assuming that there is no
- varaible exists with ``nullArg'' name.</para>
+ variable exists with <quote>nullArg</quote> name.</para>
</answer>
</qandaentry>
@@ -26413,8 +26421,8 @@ End book</programlisting>
<qandaentry xml:id="faq_questionmark">
<question>
- <para>Why do I have ``?''-s in the output instead of character
- <replaceable>X</replaceable>?</para>
+ <para>Why do I have <quote>?</quote>-s in the output instead of
+ character <replaceable>X</replaceable>?</para>
</question>
<answer>
@@ -32414,14 +32422,14 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
templates!</emphasis> Fixed the bugs of the <link
linkend="ref_builtin_c"><literal>c</literal> built-in</link>
(<literal>?c</literal>) that sometimes caused whole numbers to
- be formatted with ``.0'' at the end (like: 1.0), and caused
- numbers sometimes formatted to exponential form (like 4E-20).
- From now whole numbers will never use decimal dot (not even if
- the wrapped number is a <literal>double</literal>; remember, the
- template language knows only a single numerical type), and
- exponential form will never be used either. Also, the maximum
- number of digits after the decimal dot was limited to 16, so
- numbers smaller than 1E-16 will be shown as 0.</para>
+ be formatted with <quote>.0</quote> at the end (like: 1.0), and
+ caused numbers sometimes formatted to exponential form (like
+ 4E-20). From now whole numbers will never use decimal dot (not
+ even if the wrapped number is a <literal>double</literal>;
+ remember, the template language knows only a single numerical
+ type), and exponential form will never be used either. Also, the
+ maximum number of digits after the decimal dot was limited to
+ 16, so numbers smaller than 1E-16 will be shown as 0.</para>
</listitem>
</itemizedlist>
</section>
@@ -32869,12 +32877,12 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<literal><replaceable>myString</replaceable>[<replaceable>from</replaceable>..<<replaceable>toExclusive</replaceable>]</literal>.)
Sequence (list) slices still has to be get with the old syntax,
since <literal>substring</literal> only applies to strings.
- Please note that the ``to'' parameter is 1 greater with this new
- builtin, as it is an exclusive index. Further difference is that
- the <literal>substring</literal> built-in requires that the
- ``from'' index is less than or equal to the ``to'' index. So 0
- length substrings are possible now, but not reversed
- substrings.</para>
+ Please note that the <quote>to</quote> parameter is 1 greater
+ with this new builtin, as it is an exclusive index. Further
+ difference is that the <literal>substring</literal> built-in
+ requires that the <quote>from</quote> index is less than or
+ equal to the <quote>to</quote> index. So 0 length substrings are
+ possible now, but not reversed substrings.</para>
</listitem>
<listitem>
@@ -33209,8 +33217,8 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<itemizedlist>
<listitem>
- <para>New built-in for formatting numbers for ``computer
- audience'' as opposed to human audience: <link
+ <para>New built-in for formatting numbers for <quote>computer
+ audience</quote> as opposed to human audience: <link
linkend="ref_builtin_c"><literal>c</literal></link>. It should
be used for numbers that must use Java language formatting
regardless of the number format and locale settings, like for a
@@ -33381,7 +33389,8 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<listitem>
<para>Bugfix: The <literal>DefaultObjectWrapper</literal> has
ignored the value of the <literal>nullModel</literal> property.
- (Note that it's discouraged to use a ``null model''.)</para>
+ (Note that it's discouraged to use a <quote>null
+ model</quote>.)</para>
</listitem>
</itemizedlist>
</section>
@@ -33697,13 +33706,13 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
the 2.2.x series (see the list below), so you may choose to use it for
new projects only.</para>
- <para>Probably the most ``loudly promoted'' new feature is the totally
- redesigned XML wrapper. With the new XML wrapper FreeMarker targets a
- new application domain, which is similar to the application domain of
- XSLT: transforming complex XML to whatever textual output. Although
- this subproject is young, it is definitely usable in practice. See the
- <link linkend="xgui">XML Processing Guide</link> for more
- details.</para>
+ <para>Probably the most <quote>loudly promoted</quote> new feature is
+ the totally redesigned XML wrapper. With the new XML wrapper
+ FreeMarker targets a new application domain, which is similar to the
+ application domain of XSLT: transforming complex XML to whatever
+ textual output. Although this subproject is young, it is definitely
+ usable in practice. See the <link linkend="xgui">XML Processing
+ Guide</link> for more details.</para>
<section>
<title>Non backward-compatible changes!</title>
@@ -33923,8 +33932,8 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<listitem>
<para>A new header parameter, <literal>strip_text</literal>,
that removes all top-level text from a template. This is useful
- for ``include files'' to suppress newlines that separate the
- macro definitions. See <link
+ for <quote>include files</quote> to suppress newlines that
+ separate the macro definitions. See <link
linkend="ref.directive.ftl"><literal>ftl</literal>
directive</link></para>
</listitem>
@@ -34358,7 +34367,7 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<itemizedlist>
<listitem>
<para>Bugfix: Fixing a fatal bug in the template cache that
- was introduced with the latest cache ``bugfix''. The template
+ was introduced with the latest cache bugfix. The template
cache has always reloaded the unchanged template when the
update delay has been elapsed, until the template has been
actually changed, in which case it has never reloaded the
@@ -34528,10 +34537,10 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
</listitem>
<listitem>
- <para>From now, if no XPath engine is available, and the hash
- key in an ``XML query'' can't be interpreted without XPath, an
- error will tell this clearly, rather than silently returning
- undefined variable (null).</para>
+ <para>From now on, if no XPath engine is available, and the
+ hash key in an XML query can't be interpreted without XPath,
+ an error will tell this clearly, rather than silently
+ returning undefined variable (null).</para>
</listitem>
<listitem>
@@ -34730,9 +34739,9 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
reworked and is absolutely incompatible with pre 10. Don't
worry about this if none of your XML input documents use
you use <literal>xmlns</literal> attributes. Worry,
- though, if you have utilized the ``loose mode'', where
- only the local name of elements were compared, because
- that's now gone. Sorry...</para>
+ though, if you have utilized the <quote>loose
+ mode</quote>, where only the local name of elements were
+ compared, because that's now gone. Sorry...</para>
</listitem>
<listitem>
@@ -35233,10 +35242,11 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<itemizedlist>
<listitem>
<para>Bugfix: Fixing a fatal bug in the template cache that was
- introduced with the latest cache ``bugfix''. The template cache
- has always reloaded the unchanged template when the update delay
- has been elapsed, until the template has been actually changed,
- in which case it has never reloaded the template anymore.</para>
+ introduced with the latest cache <quote>bugfix</quote>. The
+ template cache has always reloaded the unchanged template when
+ the update delay has been elapsed, until the template has been
+ actually changed, in which case it has never reloaded the
+ template anymore.</para>
</listitem>
</itemizedlist>
</section>
@@ -35321,8 +35331,8 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<listitem>
<para>Fixes and improvements in the Manual and in the API
JavaDoc. The documentation now works with the Eclipse help
- plugin (accessible in the ``Editor/IDE plugins'' section of the
- FreeMarker Web page).</para>
+ plugin (accessible in the <quote>Editor/IDE plugins</quote>
+ section of the FreeMarker Web page).</para>
</listitem>
<listitem>
@@ -35669,11 +35679,11 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<literal><nested></literal>, then that will be
misinterpreted as a directive. To prevent this kind of problem
in the future, we recommend everybody to switch from the old
- syntax to the new syntax (``strict syntax''). The strict syntax
- will be the the default syntax starting from some of the later
- releases anyway. We plan to release a conversion tool for
- converting old templates. For more information please read:
- <xref linkend="ref_depr_oldsyntax"/></para>
+ syntax to the new syntax (<quote>strict syntax</quote>). The
+ strict syntax will be the the default syntax starting from some
+ of the later releases anyway. We plan to release a conversion
+ tool for converting old templates. For more information please
+ read: <xref linkend="ref_depr_oldsyntax"/></para>
</listitem>
<listitem>
@@ -35748,14 +35758,14 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<listitem>
<para>Namespaces: Names-spaces are invaluable if you want to
- assemble collections (``libraries'') of macros and transforms
- (and other variables), and then use them in any template without
- worrying about accidental name clashes with the application
- specific and temporary variables, or with the variables of other
- collections you want to use in the same template. This is
- extremely important if FreeMarker users want to share their
- macro/transform collections. For more information read: <xref
- linkend="dgui_misc_namespace"/></para>
+ assemble collections (<quote>libraries</quote>) of macros and
+ transforms (and other variables), and then use them in any
+ template without worrying about accidental name clashes with the
+ application specific and temporary variables, or with the
+ variables of other collections you want to use in the same
+ template. This is extremely important if FreeMarker users want
+ to share their macro/transform collections. For more information
+ read: <xref linkend="dgui_misc_namespace"/></para>
</listitem>
<listitem>
@@ -36809,11 +36819,12 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
</listitem>
<listitem>
- <para>Bugfix: operator ``or'' (<literal>||</literal>) worked
- wrongly when its left operand was a composite expression (e.g.
- the second <literal>||</literal> in <literal>false || true ||
- false</literal>; this was evaluated to <literal>false</literal>,
- but it should be <literal>true</literal>)</para>
+ <para>Bugfix: operator <quote>or</quote> (<literal>||</literal>)
+ worked wrongly when its left operand was a composite expression
+ (e.g., the second <literal>||</literal> in <literal>false ||
+ true || false</literal>; this was evaluated to
+ <literal>false</literal>, but it should be
+ <literal>true</literal>)</para>
</listitem>
<listitem>
@@ -36902,8 +36913,9 @@ TemplateModel x = env.getVariable("x"); // get variable x</programlisting>
<para>Note however that the programmer can configure
FreeMarker so that it ignores certain errors (say, undefined
variables), and continues template processing by skipping
- the problematic part. This ``loose'' policy should be used
- only for sites that don't show critical information.</para>
+ the problematic part. This <quote>loose</quote> policy
+ should be used only for sites that don't show critical
+ information.</para>
</listitem>
<listitem>
@@ -38256,8 +38268,9 @@ Apache Software Foundation.</programlisting>
<glossdef>
<para>A symbol that people use in writing. Examples of characters:
- Latin capital letter A (``A''), Latin small letter A (``a''), digit
- four (``4''), number sign (``#''), colon (``:'')</para>
+ Latin capital letter A (<quote>A</quote>), Latin small letter A
+ (<quote>a</quote>), digit four (<quote>4</quote>), number sign
+ (<quote>#</quote>), colon (<quote>:</quote>)</para>
</glossdef>
</glossentry>
@@ -38295,8 +38308,8 @@ Apache Software Foundation.</programlisting>
<glossdef>
<para>Means output <link linkend="gloss.charset">charset</link>. In
- the Java world the term ``encoding'' is commonly (mis)used as a
- synonym to ``charset''.</para>
+ the Java world the term <quote>encoding</quote> is commonly (mis)used
+ as a synonym to charset.</para>
</glossdef>
</glossentry>
@@ -38305,8 +38318,8 @@ Apache Software Foundation.</programlisting>
<glossdef>
<para>Means template <link linkend="gloss.charset">charset</link>. In
- the Java world the term ``encoding'' is commonly (mis)used as a
- synonym to ``charset''.</para>
+ the Java world the term <quote>encoding</quote> is commonly (mis)used
+ as a synonym to charset.</para>
</glossdef>
</glossentry>
@@ -38469,13 +38482,14 @@ Apache Software Foundation.</programlisting>
text (say, when you read the text with Windows notepad). Typically you
type this character by hitting ENTER or RETURN key. The line break is
represented with different characters on different platforms (to cause
- incompatibility and confusion...): ``line feed'' character on UNIX-es,
- ``carriage return'' character on Macintosh, ``carriage return''+``line
- feed'' (two characters!) on Windows and DOS. Note that line breaks in
- HTML do not have a visual effect when viewed in a browser; you must
- use markup such as <literal><BR></literal> for that. This manual
- never means <literal><BR></literal> when it says
- ``line-break''.</para>
+ incompatibility and confusion...): <quote>line feed</quote> character
+ on UNIX-es, <quote>carriage return</quote> character on Macintosh,
+ <quote>carriage return</quote> + <quote>line feed</quote> (two
+ characters!) on Windows and DOS. Note that line breaks in HTML do not
+ have a visual effect when viewed in a browser; you must use markup
+ such as <literal><BR></literal> for that. This manual never
+ means <literal><BR></literal> when it says
+ <quote>line-break</quote>.</para>
</glossdef>
</glossentry>
@@ -38629,11 +38643,12 @@ Apache Software Foundation.</programlisting>
<literal>"fo*"</literal> matches <literal>"f"</literal>,
<literal>"fo"</literal>, <literal>"foo"</literal>, etc. Regular
expressions are used in several languages and other tools. In
- FreeMarker, the usage of them is a ``power user'' option. So if you
- have never used them before, there is no need to worry about not being
- familiar with them. But if you are interested in regular expressions,
- you can find several Web pages and books about them. FreeMarker uses
- the variation of regular expressions described at: <link
+ FreeMarker, the usage of them is a <quote>power user</quote> option.
+ So if you have never used them before, there is no need to worry about
+ not being familiar with them. But if you are interested in regular
+ expressions, you can find several Web pages and books about them.
+ FreeMarker uses the variation of regular expressions described at:
+ <link
xlink:href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html</link></para>
</glossdef>
</glossentry>
@@ -38663,7 +38678,8 @@ Apache Software Foundation.</programlisting>
<glossdef>
<para>A sequence of <link linkend="gloss.character">characters</link>
- such as ``m'', ``o'', ``u'', ``s'', ``e''.</para>
+ such as <quote>m</quote>, <quote>o</quote>, <quote>u</quote>,
+ <quote>s</quote>, <quote>e</quote>.</para>
</glossdef>
</glossentry>
@@ -38761,12 +38777,13 @@ Apache Software Foundation.</programlisting>
<glossdef>
<para>This is international standard (ISO-10646) that defines a huge
set of <link linkend="gloss.character">characters</link> and assigns a
- unique number for each character (``!'' is 33, ..., ``A'' is 61, ``B''
- is 62, ..., Arabic letter hamza is 1569... etc.). This character set
- (not charset) contains almost all characters used today (Latin
- alphabet, Cyrillic alphabet, Chinese letters, etc.). The idea behind
- UCS is that we can specify any character with a unique number, not
- mater what the platform or the language is.</para>
+ unique number for each character (<quote>!</quote> is 33, ...,
+ <quote>A</quote> is 61, <quote>B</quote> is 62, ..., Arabic letter
+ hamza is 1569... etc.). This character set (not charset) contains
+ almost all characters used today (Latin alphabet, Cyrillic alphabet,
+ Chinese letters, etc.). The idea behind UCS is that we can specify any
+ character with a unique number, not mater what the platform or the
+ language is.</para>
<glossseealso otherterm="gloss.unicode"/>
</glossdef>