Return-Path: 
 <commits-return-618-apmail-velocity-commits-archive=velocity.apache.org@velocity.apache.org>
Delivered-To: apmail-velocity-commits-archive@locus.apache.org
Received: (qmail 87745 invoked from network); 26 Apr 2007 00:16:46 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 26 Apr 2007 00:16:46 -0000
Received: (qmail 33739 invoked by uid 500); 26 Apr 2007 00:16:53 -0000
Delivered-To: apmail-velocity-commits-archive@velocity.apache.org
Received: (qmail 33709 invoked by uid 500); 26 Apr 2007 00:16:53 -0000
Mailing-List: contact commits-help@velocity.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@velocity.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@velocity.apache.org>
List-Post: <mailto:commits@velocity.apache.org>
List-Id: <commits.velocity.apache.org>
Reply-To: dev@velocity.apache.org
Delivered-To: mailing list commits@velocity.apache.org
Received: (qmail 33696 invoked by uid 99); 26 Apr 2007 00:16:53 -0000
Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 25 Apr 2007 17:16:53 -0700
X-ASF-Spam-Status: No, hits=-99.5 required=10.0
	tests=ALL_TRUSTED,NO_REAL_NAME
X-Spam-Check-By: apache.org
Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 25 Apr 2007 17:16:43 -0700
Received: by eris.apache.org (Postfix, from userid 65534)
	id 66E391A9844; Wed, 25 Apr 2007 17:16:23 -0700 (PDT)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r532551 [2/2] -
 /velocity/docs/src/docbook/userguide/VelocityUsersGuide.xml
Date: Thu, 26 Apr 2007 00:16:23 -0000
To: commits@velocity.apache.org
From: henning@apache.org
X-Mailer: svnmailer-1.1.0
Message-Id: <20070426001623.66E391A9844@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org


Modified: velocity/docs/src/docbook/userguide/VelocityUsersGuide.xml
URL: http://svn.apache.org/viewvc/velocity/docs/src/docbook/userguide/VelocityUsersGuide.xml?view=diff&rev=532551&r1=532550&r2=532551
==============================================================================
--- velocity/docs/src/docbook/userguide/VelocityUsersGuide.xml (original)
+++ velocity/docs/src/docbook/userguide/VelocityUsersGuide.xml Wed Apr 25 17:16:22 2007
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <!--
  Copyright 2006 The Apache Software Foundation.
 
@@ -31,7 +31,7 @@
     <productname>Velocity</productname>
 
     <authorgroup>
-      <corpauthor>The Jakarta Velocity Developers</corpauthor>
+      <corpauthor>The Apache Velocity Developers</corpauthor>
     </authorgroup>
 
     <mediaobject>
@@ -53,7 +53,7 @@
       content providers get acquainted with Velocity and the syntax of its
       simple yet powerful scripting language, the Velocity Template Language
       (VTL). Many of the examples in this guide deal with using Velocity to
-      embed dynamic content in web sites, but all VTL examples are equally
+      embed dynamic content in web sites, but all examples are equally
       applicable to other pages and templates.</para>
 
       <para><emphasis role="bold">Thanks for choosing
@@ -69,6 +69,18 @@
       Castura in preparing this first version.</para>
     </section>
 
+    <section id="section-audience">
+      <title>Intended Audience</title>
+
+      <para>This guide is for you if you want to learn how to use the Velocity
+      Templating Language (VTL). It is intended for designers, template
+      writers and developers that are familiar with creating content templates
+      or web pages. If you want to embed the Velocity engine into your own
+      application, you probably want to consult the Velocity Developers Guide
+      available from <uri>http://velocity.apache.org/</uri> and use this guide
+      as a reference.</para>
+    </section>
+
     <section id="section-feedback">
       <title>Feedback</title>
 
@@ -78,7 +90,7 @@
 
       <variablelist>
         <varlistentry>
-          <term><email>velocity-user@jakarta.apache.org</email></term>
+          <term><email>user@velocity.apache.org</email></term>
 
           <listitem>
             <para>This mailing list is intended for discussion about using
@@ -90,7 +102,7 @@
         </varlistentry>
 
         <varlistentry>
-          <term><email>velocity-dev@jakarta.apache.org</email></term>
+          <term><email>dev@velocity.apache.org</email></term>
 
           <listitem>
             <para>This mailing list is intended for discussion about
@@ -102,37 +114,41 @@
       </variablelist>
 
       <para>Please check also the Velocity Homepage located at
-      <uri>http://jakarta.apache.org/velocity/</uri> for up-to-date
-      information, new releases and general Velocity information.</para>
+      <uri>http://velocity.apache.org/</uri> for up-to-date information, new
+      releases and general Velocity information.</para>
     </section>
   </chapter>
 
   <chapter id="chapter-what-is-velocity">
     <title>What is Velocity?</title>
 
-    <para>Velocity is a Java-based template engine. It permits web page
-    designers to reference methods defined in Java code. Template developers
-    can work in parallel with Java programmers to develop web sites according
-    to the Model-View-Controller (MVC) model, meaning that they can focus
-    solely on creating templates, and programmers can focus solely on writing
-    Java code. Velocity separates Java code from the template pages, making a
-    project more maintainable over the long run.</para>
+    <para>The Apache Velocity templating engine (or short
+    <firstterm>Velocity</firstterm> is a template engine written in 100% pure
+    Java. It permits web page designers to reference methods defined in Java
+    code. Template developers can work in parallel with Java programmers to
+    develop web sites according to the Model-View-Controller (MVC) model,
+    meaning that they can focus solely on creating templates, and programmers
+    can focus solely on writing Java code. Velocity separates Java code from
+    the template pages, making a project more maintainable over the long
+    run.</para>
 
-    <para>In a web context, Velocit provides a viable alternative to Java
+    <para>In a web context, Velocity provides a viable alternative to Java
     Server Pages (JSPs) or PHP.</para>
 
     <para>Velocity can be used to generate web pages, Java source code, SQL,
-    PostScript and other output from templates. It can be used either as a
-    standalone utility for generating source code and reports, or as an
-    integrated component of other systems.</para>
-
-    <para>Velocity provides template services for a number of web frameworks,
-    e.g. the Turbine web application framework. In this contect, Velocity
-    offers a template service that will allow web applications to be developed
+    PostScript and other output from <firstterm>templates</firstterm>. It can
+    be used either as a standalone utility for generating source code and
+    reports, or as a component integrated into frameworks or larger
+    applications.</para>
+
+    <para>Velocity provides template services for a number of other projects,
+    e.g. the Turbine web application framework
+    (<uri>http://jakarta.apache.org/turbine/</uri>). In this context, Velocity
+    offers a template service that allows development of web applications
     according to a true MVC model.</para>
 
-    <section id="section-the-fruit-store-example">
-      <title>The Fruit Store Example</title>
+    <section id="section-the-fruit-store">
+      <title>The Fruit Store</title>
 
       <para>Suppose you are a page designer for an online store that
       specializes in selling fruits. Let's call it <emphasis>The Online Fruit
@@ -142,50 +158,57 @@
       Right now, apples on sale, which are very popular. A minority of your
       customers regularly buy mangos, which are also on sale, though not as
       popular and usually relegated to the margin of your web page.
-      Information about each customer is tracked in your database, so one day
-      the question arises: <emphasis>Why not use Velocity to target special
-      deals on fruit to the customers who are most interested in those types
-      of fruits?</emphasis></para>
+      Information about each customer is tracked in a database, so one day the
+      question arises: <emphasis>Why not use Velocity to target special deals
+      on fruit to the customers who are most interested in those types of
+      fruits?</emphasis></para>
 
       <para>Velocity makes it easy to customize web pages to your online
       visitors. As a web site designer at <emphasis>The Online Fruit
-      Store</emphasis>, you want to make the web page that the customer will
-      see after logging into your site.</para>
+      Store</emphasis>, you will modify the web page that the customer sees
+      after logging into your site.</para>
 
       <para>You meet with software engineers at your company, and everyone has
       agreed that <literal>$customer</literal> will hold information
-      pertaining to the customer currently logged in, that
+      pertaining to the customer currently logged in and that
       <literal>$fruitSpecial</literal> will be all the types of fruit on sale
       at present. The <literal>$promoTool</literal> object contains methods
-      that help with promotion. For the task at hand, let's concern ourselves
-      only with these three references. Remember, you don't need to worry
-      about how the software engineers extract the necessary information from
-      the database, you just need to know that it works. This lets you get on
-      with your job, and lets the software engineers get on with
-      theirs.</para>
+      that help with promotion.</para>
+
+      <para>For the task at hand, let's concern ourselves only with these
+      three references. Remember, you don't need to worry about how the
+      software engineers extract the necessary information from the database,
+      you just need to know that it works. This lets you get on with your job,
+      and lets the software engineers get on with theirs.</para>
+
+      <para>The next example shows how to display promotions using
+      Velocity.</para>
 
-      <para>You could embed the following VTL statement in the web
-      page:</para>
+      <example id="example-displaying-the-promotions-for-the-fruit-store">
+        <title>Displaying the promotions for the Fruit Store</title>
 
-      <programlisting>&lt;html&gt;&lt;body&gt;
+        <programlisting>&lt;html&gt;
+  &lt;body&gt;
 Hello $customer.Name!
-&lt;table&gt;
-  #foreach( $fruit in $fruitSpecial )
-    #if ( $customer.hasPurchased($fruit) )
-      &lt;tr&gt;
-        &lt;td&gt;
-          $promoTool.getPromo($fruit)
-        &lt;/td&gt;
-      &lt;/tr&gt;
-    #end
-  #end
-&lt;/table&gt;
-&lt;/body&gt;&lt;/html&gt;</programlisting>
+    &lt;table&gt;
+      #foreach( $fruit in $fruitSpecial )
+        #if ( $customer.hasPurchased($fruit) )
+          &lt;tr&gt;
+            &lt;td&gt;
+              $promoTool.getPromo($fruit)
+            &lt;/td&gt;
+          &lt;/tr&gt;
+        #end
+      #end
+    &lt;/table&gt;
+  &lt;/body&gt;
+&lt;/html&gt;</programlisting>
+      </example>
 
       <para>The exact details of the <literal>#foreach</literal> and
-      <literal>#if</literal> statement will be described in greater depth in
-      the <link linkend="chapter-directives">Directives chapter</link>; what's
-      important is the impact this short script may have on your web site.
+      <literal>#if</literal> directive will be described in greater depth in
+      the <link linkend="chapter-directives">directives chapter</link>; what is
+      important is the impact this short piece of code has on your web site.
       When a customer with a penchant for mangos logs in, and mangos are on
       sale, that is what this customer will see, prominently displayed. If
       another customer with a long history of apple purchases logs in, the
@@ -193,21 +216,20 @@
       Velocity is enormous and limited only by your creativity.</para>
 
       <para>This manual should help you get started with Velocity and the
-      Velocity Template Language. It has a companion manual, <firstterm>The
-      Velocity Developers Guide</firstterm>, which describes how to integrate
-      Velocity into your own web applications (this is what the software
-      engineers at your company want to read).</para>
+      Velocity Template Language. It has a companion manual, the
+      <firstterm>Velocity Developers Guide</firstterm>, which describes how to
+      integrate Velocity into your own web applications (this is what the
+      software engineers at your company want to read).</para>
     </section>
 
     <section id="section-velocity-template-language-introduction">
-      <title>Velocity Template Language (VTL): An Introduction</title>
+      <title>An introduction to the Velocity Template Language</title>
 
       <para>The <firstterm>Velocity Template Language</firstterm>
       (<firstterm>VTL</firstterm>) is meant to provide an easy, simple and
       clean way to incorporate dynamic content in a web page. Even a web page
-      developer with little or no programming experience should soon be
-      capable of using VTL to incorporate dynamic content in a web
-      site.</para>
+      developer with little or no programming experience will soon be capable
+      of using VTL to incorporate dynamic content in a web site.</para>
 
       <para>VTL uses <firstterm>references</firstterm> to embed dynamic
       content in a web site, and a variable is one type of reference. They can
@@ -221,29 +243,30 @@
         <programlisting>#set( $a = "Velocity" )</programlisting>
       </example>
 
-      <para>This VTL statement, like all VTL statements, begins with the
-      <literal>#</literal> character and contains a directive:
-      <literal>set</literal>. When an online visitor requests your web page,
-      the Velocity Templating Engine will search through your web page to find
-      all <literal>#</literal> characters, then determine which mark the
-      beginning of VTL statements, and which of the <literal>#</literal>
-      characters that have nothing to do with VTL.</para>
+      <para>This VTL statement begins with the <literal>#</literal> character
+      and contains a <firstterm>directive</firstterm>: <literal>set</literal>.
+      When an online visitor requests your web page, Velocity will search
+      through your web page to find all <literal>#</literal> characters, then
+      determine which mark the beginning of VTL statements, and which of the
+      <literal>#</literal> characters that have nothing to do with VTL.</para>
 
       <para>The <literal>#</literal> character is followed by a directive,
       <literal>set</literal>. The <literal>set</literal> directive uses an
       expression (enclosed in brackets) -- an equation that assigns a value to
-      a <firstterm>variable</firstterm>. The variable is listed on the left
-      hand side and its value on the right hand side; the two are separated by
-      an <literal>=</literal> character.</para>
-
-      <para>In the example above, the variable is <literal>$a</literal> and
-      the value is <literal>Velocity</literal>. This variable, like all
-      references, begins with the <literal>$</literal> character. String
-      values are always enclosed in quotes, either single or double quotes.
-      Single quotes will ensure that the quoted value will be assigned to the
-      reference as is. Double quotes allow you to use velocity references and
-      directives to interpolate, such as <literal>"Hello $name"</literal>,
-      where the <literal>$name</literal> will be replaced by the current value
+      a reference. The reference is listed on the left hand side and its value
+      on the right hand side; the two are separated by an <literal>=</literal>
+      character.</para>
+
+      <para>In the example above, the reference is <literal>$a</literal> and
+      the value is <literal>Velocity</literal>. A reference always begins with
+      the <literal>$</literal> character.</para>
+
+      <para>The value on the right side represents a string value. These are
+      always enclosed in quotes, either single or double quotes. Single quotes
+      will ensure that the quoted value will be assigned to the reference
+      <emphasis>as is</emphasis>. Double quotes allow you to use Velocity
+      references ot interpolate, such as <literal>"Hello $name"</literal>,
+      where the <literal>$name</literal> will be replaced by its current value
       before that string literal is assigned to the left hand side of the
       <literal>=</literal>.</para>
 
@@ -253,22 +276,25 @@
       used to do something.</para>
 
       <para>In the example above, <literal>#set</literal> is used to assign a
-      value to a variable. The variable, <literal>$a</literal>, can then be
+      value to a reference. The reference, <literal>$a</literal>, can then be
       used in the template to output <literal>Velocity</literal>.</para>
     </section>
 
     <section id="section-hello-velocity-world">
       <title>Hello Velocity World!</title>
 
-      <para>Once a value has been assigned to a variable, you can reference
-      the variable anywhere in your HTML document. In the following example, a
-      value is assigned to <literal>$foo</literal> and later
-      referenced.</para>
+      <para>Once a value has been assigned to a reference, you can use it
+      anywhere in your HTML document. In the following example, a value is
+      assigned to <literal>$name</literal> and later referenced.</para>
 
-      <programlisting>&lt;html&gt;&lt;body&gt;
+      <example id="example-hello-velocity-world">
+        <title>"Hello World" using Velocity</title>
+
+        <programlisting>&lt;html&gt;&lt;body&gt;
 #set( $name = "Velocity" )
 Hello $name World!
 &lt;/body&gt;&lt;/html&gt;</programlisting>
+      </example>
 
       <para>The result is a web page that reads</para>
 
@@ -304,36 +330,53 @@
     <para>Each of these elements will be introduced in this chapter.</para>
 
     <section id="section-directives">
-      <title>Statements and Directives</title>
+      <title>Statements and directives</title>
 
       <para>Velocity directives are language elements than allow the template
       designer to manipulate the rendering of the template. A directive is
       part of a Velocity statement:</para>
 
-      <programlisting>#set($a = 10)           ## Velocity single-line statement
-^\_/\_______/
-| |     |
-| |     +---------- expression in brackets 
-| |
-| +---------------- Velocity directive
-|
-+------------------ begin of Velocity statement
-
+      <programlisting>## Velocity single-line statement
+#<co id="co-statement-hash" linkends="ca-statement-hash"/>set<co
+          id="co-statement-directive" linkends="ca-statement-directive"/>($a = 10)<co
+          id="co-statement-expression" linkends="ca-statement-expression"/>
+
+## Velocity multi-line statement
+#<co id="co-statement-hash2" linkends="ca-statement-hash"/>foreach<co
+          id="co-statement-directive2" linkends="ca-statement-directive"/>($i in [0..10])<co
+          id="co-statement-expression2" linkends="ca-statement-expression"/>
+  Counter is $i <co id="co-statement-body" linkends="ca-statement-body"/>
+#end<co id="co-statement-end" linkends="ca-statement-end"/></programlisting>
+
+      <calloutlist>
+        <callout arearefs="co-statement-hash co-statement-hash2"
+                 id="ca-statement-hash">
+          <para>Begin of Velocity statement (hash symbol)</para>
+        </callout>
+
+        <callout arearefs="co-statement-directive co-statement-directive2"
+                 id="ca-statement-directive">
+          <para>Velocity directive</para>
+        </callout>
+
+        <callout arearefs="co-statement-expression co-statement-expression2"
+                 id="ca-statement-expression">
+          <para>Expression in brackets</para>
+        </callout>
+
+        <callout arearefs="co-statement-body" id="ca-statement-body">
+          <para>Multi-line statement body</para>
+        </callout>
+
+        <callout arearefs="co-statement-end" id="ca-statement-end">
+          <para>Multi-line statement end</para>
+        </callout>
+      </calloutlist>
 
+      <para>Velocity knows about <firstterm>single-line statements</firstterm>
+      and <firstterm>multi-line statements</firstterm>.</para>
 
-+------------------ begin of Velocity statement
-|
-|   +-------------- Velocity directive
-|   |
-|   |          +--- expression in brackets
-| __|__  ______|______
-v/     \/             \
-#foreach($i in [0..10])   ## Velocity multi-line statement
-  Counter is $i           ## statement body
-#end                      ## end of Velocity multi-line statement</programlisting>
-
-      <para>Velocity knows about single-line and multi-line statements. A
-      single-line statement starts with a single <literal>#</literal>
+      <para>A single-line statement starts with a single <literal>#</literal>
       character, followed by directive itself. Some directives also take
       parameters in brackets. A single-line statement then ends
       immediately.</para>
@@ -352,11 +395,11 @@
 
       <para>A multi-line statement starts like a single-line statement, but
       also has a statement body. This body ends with
-      <literal>#end</literal>.<footnote>
+      <literal>#end</literal><footnote>
           <para>Technically speaking, the opening statement and
           <literal>#end</literal> can be on the same line. We will still call
           it a multi-line statement.</para>
-        </footnote></para>
+        </footnote>.</para>
 
       <example id="example-velocity-multi-line-statements">
         <title>Velocity multi-line statements</title>
@@ -387,14 +430,18 @@
       surrounding text, it is possible to wrap it in curly braces
       (<literal>{</literal> and <literal>}</literal>):</para>
 
-      <programlisting>#{set}($name = "apple")
+      <example id="example-formal-directives">
+        <title>Velocity directives in formal notation</title>
+
+        <programlisting>#{set}($name = "apple")
 
 #{foreach}($i in [1..10])
  The count is $i
 #{end}</programlisting>
+      </example>
 
       <para>All available Velocity directives are listed in the <link
-      linkend="chapter-directives">Directives chapter</link>.</para>
+      linkend="chapter-directives">directives chapter</link>.</para>
 
       <note>
         <para>While the hash sign is technically not part of the directive, we
@@ -415,7 +462,7 @@
       followed by an <firstterm>identifier</firstterm> name.</para>
 
       <example id="example-velocity-references">
-        <title>Velocity References</title>
+        <title>Velocity references</title>
 
         <programlisting>## Simple reference
 The total amout is $total.
@@ -434,58 +481,73 @@
       surrounding template, you can wrap the reference identifier in curly
       braces (<literal>{</literal> and <literal>}</literal>):</para>
 
-      <programlisting>The total amout is ${total}.
+      <example id="example-formal-velocity-references">
+        <title>Formal velocity references</title>
+
+        <programlisting>The total amout is ${total}.
 
 You currently have ${cart.items} Items in your Shopping cart.</programlisting>
+      </example>
 
       <para>Velocity references are discussed in depth in the <link
-      linkend="chapter-references">References chapter</link>.</para>
+      linkend="chapter-references">references chapter</link>.</para>
     </section>
 
     <section id="section-comments">
       <title>Comments</title>
 
-      <para>Comments allows descriptive text to be included in a template that
+      <para>Comments allow descriptive text to be included in a template that
       is not placed into the output of the template engine. Comments are a
       useful way of reminding yourself and explaining to others what your VTL
-      statements are doing, or any other purpose you find useful.</para>
+      code is doing, or any other purpose you find useful.</para>
 
       <para>Like the Java programming language, Velocity has single-line and
       block comments.</para>
 
-      <para>A single line comment begins with <literal>##</literal> and
-      finishes at the end of the line. This is an example of a single line
-      comment in VTL:</para>
+      <para>A single-line comment begins with <literal>##</literal> and
+      finishes at the end of the line.</para>
 
-      <programlisting>## This is a single line comment.
+      <example id="example-vtl-single-line-comments">
+        <title>Single-line comments</title>
+
+        <programlisting>## This is a single-line comment.
 
 This is visible in the output ## This is a comment.</programlisting>
+      </example>
 
       <para>If you are going to write a few lines of commentary, there is no
-      need to have numerous single line comments. Multi-line comments, which
+      need to have numerous single-line comments. Multi-line comments, which
       begin with <literal>#*</literal> and end with <literal>*#</literal>, are
       available to handle this scenario:</para>
 
-      <programlisting>This is text that is outside the multi-line comment.
+      <example id="example-multi-line-comment">
+        <title>A multi-line comment</title>
+
+        <programlisting>This is text that is outside the multi-line comment.
 Online visitors can see it.
 
 #*
   Thus begins a multi-line comment. Online visitors will not
-  see this text because the Velocity Templating Engine will
+  see this text because the Velocity templating engine will
   ignore it.
 *#
 
 Here is text outside the multi-line comment; it is visible.</programlisting>
+      </example>
 
-      <para>Multiline comments can start and end in arbitrary columns of the
+      <para>Multi-line comments can start and end in arbitrary columns of the
       template.</para>
 
-      <para>There is a third type of comment, the <firstterm>VTL comment
+      <para>There is a third type of comment, the VTL <firstterm>comment
       block</firstterm>, which may be used to store such information as the
       document author and versioning information. It is similar to the Javadoc
-      comment block in the Java programming language:</para>
+      comment block in the Java programming language and starts with
+      <literal>#**</literal>.</para>
+
+      <example id="example-vtl-comment-block">
+        <title>A VTL comment block</title>
 
-      <programlisting>#**
+        <programlisting>#**
 This is a VTL comment block and
 may be used to store such information
 as the document author and versioning
@@ -493,24 +555,31 @@
 @author
 @version 5
 *#</programlisting>
+      </example>
     </section>
 
-    <section id="escaping-velocity">
+    <?hard-pagebreak ?>
+
+    <section id="section-escaping-vtl-elements">
       <title>Escaping VTL elements</title>
 
       <para>Most of the time, there is no problem, rendering a Velocity
       template because the rendering engine is quite smart about finding
-      Velocity Statements and References and distinguishing them from regular
+      Velocity statements and references and distinguishing them from regular
       text.</para>
 
-      <programlisting>## Renders as normal text, because the dollar sign 
+      <example id="example-distinguishing-between-text-and-references">
+        <title>Distinguishing between text and references</title>
+
+        <programlisting>## Renders as normal text, because the dollar sign 
 ## is not followed by a letter.
 I bought a 4 lb. sack of potatoes for only $2.50!
 
 ## Renders as variable
 I bought a 4 lb. sack of potatoes for only $money.</programlisting>
+      </example>
 
-      <para>Velocity allows for explicit escaping of References and Directives
+      <para>Velocity allows for explicit escaping of references and directives
       using the <literal><literal>\</literal></literal> (backslash) character.
       If the character following the <literal>\</literal> would start a new
       directive or reference, then this character is output verbatim. This can
@@ -540,18 +609,20 @@
       <example id="example-escaping-vtl-references">
         <title>Escaping VTL references</title>
 
-        <programlisting>$a     ## $a is a reference but an unbound on (it has no value)
+        <programlisting>$a     ## $a is a reference but an unbound one (it has no value)
        ## This renders as $a in the output
 
 \$a    ## Escaping an unbound reference renders it as \$a
 
 #set($a = 10)  ## When a value is assigned to the reference...
 
-$a     ## Now renders as 10
+$a     ## ... then it renders as 10 ...
 
-\$a    ## Now renders as $a</programlisting>
+\$a    ## ... and gets escaped and now renders as $a.</programlisting>
       </example>
 
+      <?hard-pagebreak ?>
+
       <para>Escaping VTL statements works in the same way.</para>
 
       <example id="example-escaping-vtl-statements">
@@ -567,7 +638,7 @@
 #set ($a = 10)
 \#set ($a = 20) ## Renders as #set (10 = 20)
 
-## The backslash does not escape a whole multiline statement
+## The backslash does not escape a whole multi-line statement
 ## This is a syntax error: (#end without a starting statement)
 \#if ($a == 10)
 #end</programlisting>
@@ -579,8 +650,8 @@
           <para>...and you probably thought, the worst part was over...</para>
         </footnote></para>
 
-      <example id="example-escaping-macros">
-        <title>Escaping Macros</title>
+      <example id="example-escaping-velocimacros">
+        <title>Escaping Velocimacros</title>
 
         <programlisting>#apple    ## Renders as #apple, because it is not a VTL
           ## statement
@@ -590,13 +661,13 @@
  Apple
 #end
 
-#apple    ## This is now an syntax error (#apple needs now
-          ## brackets because it's a macro)
+#apple    ## This is now a syntax error
+          ## (#apple Velocimacro invocation needs brackets)
 
-#apple()  ## Renders as Apple (VTL Macro)
+#apple()  ## Renders as Apple (invocation of a Velocimacro)
 
 \#apple   ## renders as #apple, because it is now a VTL
-          ## statement after macro definition.</programlisting>
+          ## statement after Velocimacro definition.</programlisting>
       </example>
     </section>
   </chapter>
@@ -608,9 +679,9 @@
     <firstterm>variables</firstterm>, <firstterm>properties</firstterm> and
     <firstterm>methods</firstterm>. They are the glue that connects the
     business logic of your application written in Java to your templates. The
-    Java code and the templates must use the same set of references, so you,
-    as a template designer and the developers writing the application logic
-    must agree on the references available for use on the templates.</para>
+    Java code and the templates must use the same set of references, so you as
+    a template designer and the developers writing the application logic must
+    agree on the references available for use on the templates.</para>
 
     <para>Every reference that is output when a template is rendered, is
     converted to a Java string by calling the <literal>toString()</literal>
@@ -622,9 +693,9 @@
       <title>Identifiers</title>
 
       <para>All references consist of a leading <literal>$</literal> character
-      followed by a VTL <firstterm>Identifier</firstterm>. A VTL Identifier
-      must start with an alphabetic character (a..z or A..Z). The rest of the
-      characters are limited to the following types of characters:</para>
+      followed by a VTL identifier. A VTL identifier must start with an
+      alphabetic character (a..z or A..Z). The rest of the characters are
+      limited to the following types of characters:</para>
 
       <para><itemizedlist spacing="compact">
           <listitem>
@@ -637,13 +708,13 @@
           </listitem>
 
           <listitem>
-            <para>hyphen and underscore: <literal>-</literal> and
-            <literal>_</literal></para>
+            <para>hyphen and underscore (<literal>-</literal> and
+            <literal>_</literal>)</para>
           </listitem>
         </itemizedlist></para>
 
       <para>Velocity identifiers are, just as Java variable names,
-      case-sensitive.</para>
+      <emphasis>case-sensitive</emphasis>.</para>
     </section>
 
     <section id="section-variables">
@@ -653,7 +724,7 @@
       reference is also a variable. Each variable represents a Java
       object.</para>
 
-      <example>
+      <example id="example-valid-variable-names">
         <title>Valid variable names</title>
 
         <programlisting>$foo
@@ -663,21 +734,25 @@
 $fooBar1</programlisting>
       </example>
 
-      <para>Velocity keeps an internal map from Identifiers to Variables
-      called the <firstterm>Context</firstterm>. This map is where Java code
-      can place objects to be reference from the template.</para>
+      <para>Velocity keeps an internal map from identifiers to variables
+      called the <firstterm>context</firstterm>. The is the place where Java
+      code can put objects to be referenced from the template.</para>
 
       <para>A variable must be assigned a value before it can be referenced
       from the template. Assigning a value to a Velocity variable is the same
-      as placing an object in the Context from the Java code of your
+      as placing an object in the context from the Java code of your
       application.</para>
 
-      <programlisting>## Puts a String object representing "bar" in the Context
+      <example id="example-creating-a-context-object">
+        <title>Creating a new context object</title>
+
+        <programlisting>## Puts a String object representing "bar" in the context
 #set( $foo = "bar" )</programlisting>
+      </example>
 
       <note>
         <para>Assigning a new value using the #set statement to a variable
-        does change the object present in the Context.</para>
+        does change the object present in the context.</para>
       </note>
     </section>
 
@@ -688,9 +763,9 @@
       notation. The objects to look up the properties must be available
       through a Velocity variable and the notation consists of a leading
       variable followed by the dot ("<literal>.</literal>") character and
-      another VTL Identifier.</para>
+      another VTL identifier.</para>
 
-      <example>
+      <example id="example-valid-property-names">
         <title>Valid property names</title>
 
         <programlisting>$customer.address
@@ -701,7 +776,7 @@
       <para>A property name can represent the following elements depending on
       the object used for look-up:</para>
 
-      <itemizedlist>
+      <para><itemizedlist spacing="compact">
         <listitem>
           <para>If the object has a method
           <literal>get&lt;property&gt;</literal> where the property name is
@@ -716,19 +791,19 @@
 
         <listitem>
           <para>finally if the object used to look up the property has a
-          get(String) method, invoke this method.</para>
+          <literal>get(String)</literal> method, invoke this method.</para>
         </listitem>
-      </itemizedlist>
+      </itemizedlist></para>
 
       <para>Take the first example, <literal>$customer.address</literal>. It
       can have multiple meanings:<footnote>
-          <para>The sequence of these lookups is determined by the
-          <firstterm>Velocity Uberspector</firstterm>. This is merely the
-          default lookup. A Java developer can customize this behaviour by
-          using a custom Uberspector.</para>
+          <para>The sequence of these lookups is determined by the Velocity
+          <firstterm>Uberspector</firstterm>. This is merely the default
+          lookup. A Java developer can customize this behaviour by using a
+          custom Uberspector.</para>
         </footnote></para>
 
-      <itemizedlist>
+      <para><itemizedlist spacing="compact">
         <listitem>
           <para>when the object has a method <literal>getaddress()</literal>,
           invoke this method</para>
@@ -750,7 +825,7 @@
           <para>when the object has a method <literal>isAddress()</literal>,
           invoke this method.</para>
         </listitem>
-      </itemizedlist>
+      </itemizedlist></para>
 
       <note>
         <para>When a property name refers to a getter method,
@@ -761,26 +836,32 @@
         <literal>get(String)</literal> method,
         <literal>$obj.property</literal> and <literal>$obj.Property</literal>
         will pass different values to this <literal>get(String)</literal>
-        method. This can lead to hard-to-find problems. It's a good practice
+        method. This can lead to hard-to-find problems.</para></note>
+
+       <para>It is a good practice
         to standardize the capitalization of property names in your
-        application.</para>
-      </note>
+        application<footnote>
+            <para>While lots of the available Velocity literature uses
+            upper-case capitalization, it is actually a good idea to use
+            lower-case capitalization as this is consistent with JSTL and the regular
+            bean property notation.</para>
+          </footnote>.</para>
 
       <para>If you wonder about setting property values, please look up the
       <literal>#set()</literal> directive chapter. The setting of properties
       is discussed there.</para>
 
-      <section id="section-property-lookup-rules">
+      <section id="section-default-property-lookup-rules">
         <title>Default property lookup rules</title>
 
         <para>Velocity is quite clever when figuring out which method
-        corresponds to a requested property.<footnote>
+        corresponds to a requested property<footnote>
             <para>Some people would say that it is entirely too clever.</para>
-          </footnote>It tries out different alternatives based on several
+          </footnote>. It tries out different alternatives based on several
         established naming conventions. The exact lookup sequence depends on
         whether or not the property name starts with an upper-case letter. For
         lower-case names, such as <literal>$customer.address</literal>, the
-        sequence is <itemizedlist spacing="compact">
+        sequence is:</para> <para><itemizedlist spacing="compact">
             <listitem>
               <para><literal>getaddress()</literal></para>
             </listitem>
@@ -796,9 +877,11 @@
             <listitem>
               <para><literal>isAddress()</literal></para>
             </listitem>
-          </itemizedlist> For upper-case property names like
-        <literal>$customer.Address</literal>, it is slightly different:
-        <itemizedlist spacing="compact">
+          </itemizedlist></para>
+
+        <para>For upper-case property names like
+        <literal>$customer.Address</literal>, it is slightly different:</para>
+        <para><itemizedlist spacing="compact">
             <listitem>
               <para><literal>getAddress()</literal></para>
             </listitem>
@@ -814,10 +897,12 @@
             <listitem>
               <para><literal>isAddress()</literal></para>
             </listitem>
-          </itemizedlist>As regular bean properties tend to be written in
-        lowercase notation, you should talk to your programmers that they
-        don't add both lower-case and upper-case methods to their objects. It
-        would be a bad idea anyway.</para>
+          </itemizedlist></para>
+
+        <para>As regular bean properties tend to be written in lowercase
+        notation, you should talk to your programmers that they don't add both
+        lower-case and upper-case methods to their objects. It would be a bad
+        idea anyway.</para>
 
         <caution>
           <para>There are some exotic naming cases, such as a property
@@ -832,6 +917,8 @@
       </section>
     </section>
 
+      <?hard-pagebreak ?>
+
     <section id="section-methods">
       <title>Methods</title>
 
@@ -841,7 +928,7 @@
       parentheses following the method name. These parentheses can optionally
       contain a parameter list.</para>
 
-      <example>
+      <example id="example-valid-method-references">
         <title>Valid method references</title>
 
         <programlisting>$cart.calculateTotal()
@@ -858,17 +945,17 @@
       <para>The last few examples are similar to the examples seen earlier
       when discussing properties. As stated there, the properties notation is
       a short-hand notation for the invocation of bean getters and
-      setters.<footnote>
+      setters<footnote>
           <para>By explicitly stating the method name and parameters, the
           Uberspector is not used. This is useful if you object has both,
           <literal>get(String)</literal> and explicit property getter
           methods.</para>
-        </footnote></para>
+        </footnote>.</para>
 
-      <para>The main difference between Properties and Methods is that you can
-      specify a parameter list to a Method.</para>
+      <para>The main difference between properties and methods is that you can
+      specify a parameter list to a method.</para>
 
-      <example>
+      <example id="example-methods-that-can-be-used-with-shorthand-notation">
         <title>Methods that can be used with shorthand notation</title>
 
         <programlisting>$shop.getFruits()
@@ -891,7 +978,7 @@
       </example>
 
       <warning>
-        <para>The last <literal>#set()</literal> example will not work in
+        <para>The last <literal>#set</literal> example will not work in
         Velocity versions before 1.5 unless the <literal>$album</literal>
         object implements <literal>java.util.Map</literal>. This is a bug in
         older Velocity versions.</para>
@@ -903,7 +990,7 @@
       <literal>get&lt;property&gt;()</literal>, it must still adhere to bean
       getter and setter method signatures.</para>
 
-      <example>
+      <example id="example-methods-that-can-not-be-used-with-shorthand-notation">
         <title>Methods that can not be used with shorthand notation</title>
 
         <programlisting>## Can't pass a parameter with $sun.planet
@@ -917,11 +1004,11 @@
       </example>
     </section>
 
-    <section id="section-reference-miscelany">
-      <title>Reference Miscellany</title>
+    <section id="section-reference-miscellany">
+      <title>Reference miscellany</title>
 
-      <section id="section-formal-reference-notation">
-        <title>Separating Identifiers and template text</title>
+      <section id="section-separating-identifiers-and-template-text">
+        <title>Separating identifiers and template text</title>
 
         <para>When writing templates, you might encounter situations in which
         it is necessary to explicitly separate a reference from the
@@ -929,7 +1016,7 @@
         implicitly through whitespace. Additionally there is a formal notation
         which wraps the identifiers with curly braces:</para>
 
-        <example>
+        <example id="example-formal-notation-for-velocity-references">
           <title>Formal notation for Velocity references</title>
 
           <programlisting>${fruit}
@@ -942,7 +1029,11 @@
         juice which should be sold. Using the shorthand notation would be
         inadequate for this task. Consider the following example:</para>
 
-        <programlisting>You have selected $fruitjuice.</programlisting>
+        <example id="example-ambiguous-reference-name">
+          <title>An ambiguous reference name</title>
+
+          <programlisting>You have selected $fruitjuice.</programlisting>
+        </example>
 
         <para>There is ambiguity here, and Velocity assumes that
         <literal>$fruitjuice</literal>, not <literal>$fruit</literal>, is the
@@ -951,7 +1042,11 @@
         <literal>$fruitjuice</literal>. Using formal notation can resolve this
         problem.</para>
 
-        <programlisting>You have selected ${fruit}juice.</programlisting>
+        <example id="example-using-formal-notation">
+          <title>Using formal notation to resolve ambiguity</title>
+
+          <programlisting>You have selected ${fruit}juice.</programlisting>
+        </example>
 
         <para>Now Velocity knows that <literal>$fruit</literal>, not
         <literal>$fruitjuice</literal>, is the reference. Formal notation is
@@ -966,7 +1061,11 @@
         behavior is to output the image of the reference. For example, suppose
         the following reference appears as part of a VTL template.</para>
 
-        <programlisting>&lt;input type="text" name="email" value="$email"/&gt;</programlisting>
+        <example id="example-non-quiet-input-form">
+          <title>A web input form without quiet notation</title>
+
+          <programlisting>&lt;input type="text" name="email" value="$email"/&gt;</programlisting>
+        </example>
 
         <para>When the form initially loads, the variable reference
         <literal>$email</literal> has no value, but you probably prefer a
@@ -976,7 +1075,11 @@
         would use <literal>$!email</literal>. So the above example would look
         like the following:</para>
 
-        <programlisting>&lt;input type="text" name="email" value="$!email"/&gt;</programlisting>
+        <example id="example-quiet-input-form">
+          <title>A web input form with quiet notation</title>
+
+          <programlisting>&lt;input type="text" name="email" value="$!email"/&gt;</programlisting>
+        </example>
 
         <para>Now when the form is initially loaded and
         <literal>$email</literal> still has no value, an empty string will be
@@ -984,7 +1087,12 @@
 
         <para>Formal and quiet reference notation can be used together:</para>
 
-        <programlisting>&lt;input type="text" name="email" value="$!{email}"/&gt;</programlisting>
+        <example id="example-quiet-formal-notation">
+          <title>A web input form using quiet and formal notation
+          together</title>
+
+          <programlisting>&lt;input type="text" name="email" value="$!{email}"/&gt;</programlisting>
+        </example>
 
         <caution>
           <para>It is very easy to confuse the quiet reference notation with
@@ -1001,12 +1109,12 @@
     <title>Directives</title>
 
     <para>References allow template designers to generate dynamic content for
-    web sites, while <emphasis>Directives</emphasis> permit web designers to
+    web sites, while <emphasis>directives</emphasis> permit web designers to
     truly take charge of the appearance and content of the web site. A
     directive is a script element that can be used to manipulate the rendering
     of the template.</para>
 
-    <para>As described in Chapter 3.1, Velocity Directives are part of either
+    <para>As described above, Velocity directives are part of either
     single or multi-line statements and are preceded by a hash sign
     (<literal>#</literal>). While the hash sign is technically not part of the
     directive, we will still speak about the <literal>#if</literal> or
@@ -1019,52 +1127,52 @@
         these off.</para>
       </footnote></para>
 
-    <itemizedlist spacing="compact">
+    <para><itemizedlist spacing="compact">
       <listitem>
-        <para><literal>#set()</literal> (single line statement)</para>
+        <para><literal>#set</literal> (single-line statement)</para>
       </listitem>
 
       <listitem>
-        <para><literal>#literal()</literal> (multi line statement)</para>
+        <para><literal>#literal</literal> (multi-line statement)</para>
       </listitem>
 
       <listitem>
-        <para><literal>#if() / #elseif() / #else</literal> (multi line
+        <para><literal>#if / #elseif / #else</literal> (multi-line
         statement)</para>
       </listitem>
 
       <listitem>
-        <para><literal>#foreach()</literal> (multiline statement)</para>
+        <para><literal>#foreach</literal> (multi-line statement)</para>
       </listitem>
 
       <listitem>
-        <para><literal>#include()</literal> (single line statement)</para>
+        <para><literal>#include</literal> (single-line statement)</para>
       </listitem>
 
       <listitem>
-        <para><literal>#parse()</literal> (single line statement)</para>
+        <para><literal>#parse</literal> (single-line statement)</para>
       </listitem>
 
       <listitem>
-        <para><literal>#stop()</literal> (single line statement)</para>
+        <para><literal>#stop</literal> (single-line statement)</para>
       </listitem>
 
       <listitem>
-        <para><literal>#macro()</literal> (multi line statement, see Chapter
+        <para><literal>#macro</literal> (multi-line statement, see Chapter
         7)</para>
       </listitem>
-    </itemizedlist>
+    </itemizedlist></para>
 
     <section id="section-the-set-directive">
-      <title>The <literal>#set</literal> directive</title>
+      <title>The #set directive</title>
 
       <para>The <literal>#set</literal> directive is used for setting the
-      value of a reference. It is used in a single-line statement.</para>
+      value of a reference.</para>
 
       <para>A value can be assigned to either a variable reference or a
       property reference.</para>
 
-      <example>
+      <example id="example-value-assignment-using-the-set-directive">
         <title>Value assignment using the <emphasis>set</emphasis>
         directive</title>
 
@@ -1113,7 +1221,7 @@
           </listitem>
         </itemizedlist></para>
 
-      <example>
+      <example id="example-valid-reference-assignments">
         <title>Valid reference assignments</title>
 
         <programlisting>## variable reference
@@ -1147,8 +1255,8 @@
 
         <para>Similarly, for the Map example, the elements defined within the
         <literal>{..}</literal> operator are accessible using the methods
-        defined in the <literal>java.util.Map</literal> class. So, for
-        example, you could access the first element above using
+        defined in the <literal>java.util.Map</literal> class. You can access
+        the first element above using
         <literal>$fruit.shapes.get("Apple")</literal> to return the String
         <literal>round</literal>, or even
         <literal>$fruit.shapes.Apple</literal> to return the same
@@ -1158,7 +1266,7 @@
       <para>The RHS can also be an arithmetic expression as described in the
       Math chapter below.</para>
 
-      <example>
+      <example id="example-expression-examples">
         <title>Expression examples</title>
 
         <programlisting>#set( $value = $foo + 1 )
@@ -1167,7 +1275,7 @@
 #set( $value = $foo / $bar )</programlisting>
       </example>
 
-      <section id="section-assigning-null-values">
+      <section id="section-assigning-null-values-to-references">
         <title>Assigning null values to references</title>
 
         <para>In its default configuration, Velocity treats
@@ -1178,8 +1286,8 @@
         property (<literal>directive.set.null.allowed</literal>) exists that
         removes this restriction. If you do not want <literal>null</literal>
         values to be treated special, tell your application developers that
-        they should look up this property in the <emphasis>Velocity Developers
-        Guide</emphasis> and set it to true.</para>
+        they should look up this property in the Velocity Developers Guide and
+        set it to true.</para>
 
         <note>
           <para>Removing this restriction is one of the new features of
@@ -1283,6 +1391,8 @@
         string assigned.</para>
       </section>
 
+      <?hard-pagebreak ?>
+
       <section id="section-string-literals">
         <title>String Literals</title>
 
@@ -1290,25 +1400,33 @@
         literals that are enclosed in double quote characters will be parsed
         and rendered, as shown:</para>
 
-        <programlisting>#set( $directoryRoot = "www" )
+        <example id="example-double-quoted-string-literal">
+          <title>Evaluating a double-quoted string literal</title>
+
+          <programlisting>#set( $directoryRoot = "www" )
 #set( $templateName = "index.vm" )
 #set( $template = "$directoryRoot/$templateName" )
 $template</programlisting>
+        </example>
 
-        <para>The output will be</para>
+        <para>The output will be:</para>
 
         <programlisting>www/index.vm</programlisting>
 
         <para>However, when the string literal is enclosed in single quote
         characters, it will not be parsed:</para>
 
-        <programlisting>#set( $fruit = "apple" )
+        <example id="example-evaluating-string-literals">
+          <title>Single and double-quoted string literals</title>
+
+          <programlisting>#set( $fruit = "apple" )
 $fruit
 
 #set( $veggie = '$fruit' )
 $veggie</programlisting>
+        </example>
 
-        <para>This renders as:</para>
+        <para>The output will be:</para>
 
         <programlisting>apple
 
@@ -1317,13 +1435,14 @@
         <para>By default, rendering unparsed text using single quotes is
         activated in Velocity. This default can be changed by changing the
         <literal>runtime.interpolate.string.literals</literal> property to be
-        false. (See the <emphasis>Velocity Developers Guide</emphasis> for
-        more information).</para>
+        false. (See the Velocity Developers Guide for more
+        information).</para>
       </section>
     </section>
 
+      <?hard-pagebreak ?>
     <section id="section-the-literal-directive">
-      <title>The #literal Directive</title>
+      <title>The #literal directive</title>
 
       <para>The <literal>#literal</literal> directive allows you to easily use
       large chunks of uninterpreted content in VTL code. This can be
@@ -1331,13 +1450,17 @@
       a multi-line statement and needs a #end directive to close the statement
       body.</para>
 
-      <programlisting>#literal()
+      <example id="example-using-the-literal-directive">
+        <title>Using the <literal>#literal</literal> directive</title>
+
+        <programlisting>#literal()
 #foreach ($fruit in $basket)
   nothing will happen to $fruit
 #end
 #end</programlisting>
+      </example>
 
-      <para>Renders as:</para>
+      <para>The output will be:</para>
 
       <programlisting>#foreach ($fruit in $basket)
   nothing will happen to $fruit
@@ -1348,33 +1471,36 @@
       will still be output uninterpreted.</para>
 
       <caution>
-        <para>While <literal>#literal()</literal> suppresses the evaluation of
+        <para>While <literal>#literal</literal> suppresses the evaluation of
         Velocity directives and references at run-time, the body is still
-        parsed. <literal>#literal()</literal> is not a comment block, if you
+        parsed. <literal>#literal</literal> is not a comment block, if you
         have a syntax error (e.g. a missing <literal>#end</literal>) inside
         the block, Velocity will still report a parse error.</para>
       </caution>
     </section>
 
-    <section id="section-conditionals">
+      <?hard-pagebreak ?>
+    <section id="section-conditionals-if-elseif-else">
       <title>Conditionals - #if/#elseif/#else</title>
 
       <para>The <literal>#if</literal> directive in Velocity allows for text
       to be included when the web page is generated, on the conditional that
-      the <emphasis>if-statement</emphasis> is true. Consider the following
+      the <literal>#if</literal> statement is true. Consider the following
       piece of code:</para>
 
-      <programlisting>#if( $display )
+      <example id="example-using-the-if-directive">
+        <title>Using the <literal>#if</literal> directive</title>
+
+        <programlisting>#if( $display )
   &lt;strong&gt;Velocity!&lt;/strong&gt;
 #end</programlisting>
+      </example>
 
       <para>The variable <literal>$display</literal> is evaluated to determine
-      whether it is true, which will happen under one of two
-      circumstances:</para>
-
-      <para><itemizedlist spacing="compact">
+      whether it is true, which will happen under one of two circumstances:
+      <itemizedlist>
           <listitem>
-            <para><literal>$foo</literal> is a
+            <para><literal>$display</literal> is a
             <literal>java.lang.Boolean</literal> object (True/False) which has
             a true value.</para>
           </listitem>
@@ -1382,23 +1508,24 @@
           <listitem>
             <para>The value is not null.</para>
           </listitem>
-        </itemizedlist>The Velocity context only contains Java objects, so any
-      method that returns a boolean primitive will automatically wrapped into
-      a <literal>java.lang.Boolean</literal> object.</para>
+        </itemizedlist></para>
+
+      <para>The Velocity context only contains Java objects, so any method
+      that returns a boolean primitive will automatically wrapped into a
+      <literal>java.lang.Boolean</literal> object.</para>
 
       <para>The content between the <literal>#if</literal> and the
       <literal>#end</literal> statements becomes the output if the evaluation
-      is true. In this case, if <literal>$foo</literal> is true, the output
-      will be: <computeroutput>Velocity!</computeroutput>. Conversely, if
-      <literal>$foo</literal> has a null value, or if it is a boolean false,
-      the statement evaluates as false, and there is no output.</para>
+      is true. In this case, if <literal>$display</literal> is true, the
+      output will be: <computeroutput>Velocity!</computeroutput>. Conversely,
+      if <literal>$display</literal> has a null value, or if it is a boolean
+      false, the statement evaluates as false, and there is no output.</para>
 
       <para>An <literal>#elseif</literal> or <literal>#else</literal> element
-      can be used with an <literal>#if</literal> element. Note that the
-      Velocity Templating Engine will stop at the first expression that is
-      found to be true:</para>
+      can be used with an <literal>#if</literal> element. Note that Velocity
+      will stop at the first expression that is found to be true:</para>
 
-      <example>
+      <example id="example-using-if-elseif-else-to-select-multiple-template-pieces">
         <title>Using #if/#elseif/#else to select multiple template
         pieces</title>
 
@@ -1423,20 +1550,24 @@
 
       <para>When you wish to include text immediately following a
       <literal>#else</literal> directive you need to use curly brackets
-      immediately surrounding the directive to differentiate it from the
-      following text:</para>
+      surrounding the directive to differentiate it from the following
+      text:</para>
 
-      <programlisting>#if( $foo == $bar)it's true!#{else}it's not!#end&lt;/li&gt;</programlisting>
+      <example id="example-if-directive-in-formal-notation">
+        <title>The <literal>#if</literal> directive in formal notation</title>
+
+        <programlisting>#if( $foo == $bar)it is true!#{else}it is not!#end&lt;/li&gt;</programlisting>
+      </example>
     </section>
 
-    <section id="loops">
+    <section id="section-loops-foreach">
       <title>Loops - #foreach</title>
 
       <para><literal>#foreach</literal> iterates over the elements given in a
       List or Array element.</para>
 
-      <example>
-        <title>foreach loop example</title>
+      <example id="example-foreach-loop-example">
+        <title>A <literal>#foreach</literal> loop example</title>
 
         <programlisting>&lt;ul&gt;
   #foreach( $product in $allProducts )
@@ -1449,40 +1580,40 @@
       only loops where the number of iterations is predetermined. There is no
       <literal>do..while</literal> or <literal>repeat..until</literal> loop in
       Velocity. This has been a conscious decision to make sure that the
-      rendering process of Velocity does always terminate.<footnote>
+      rendering process of Velocity does always terminate<footnote>
           <para>It is stil possible to write a template that contains endless
           loops. It is just harder.</para>
-        </footnote></para>
+        </footnote>.</para>
 
       <para>A VTL foreach loop takes two arguments, the first one is the
       <firstterm>loop variable</firstterm> and the second is an object that
       can be iterated over. Velocity supports a number of object types in its
-      default configuration:<footnote>
+      default configuration<footnote>
           <para>The list of objects can be changed and extended, please see
-          the Developers guide on how to do this.</para>
-        </footnote><itemizedlist>
+          the Velocity Developers Guide on how to do this.</para>
+        </footnote>:</para><para><itemizedlist spacing="compact">
           <listitem>
             <para>Any array type</para>
           </listitem>
 
           <listitem>
-            <para><literal>java.lang.Collection</literal> The loop iterates
+            <para><literal>java.lang.Collection</literal> - The loop iterates
             over the Iterator returned by obj.iterator()</para>
           </listitem>
 
           <listitem>
-            <para><literal>java.lang.Map</literal> The loop will iterate over
-            the values of the Map using the iterator returned by
+            <para><literal>java.lang.Map</literal> - The loop will iterate
+            over the values of the Map using the iterator returned by
             values().iterator()</para>
           </listitem>
 
           <listitem>
-            <para><literal>java.lang.Iterator</literal> Velocity uses this
+            <para><literal>java.lang.Iterator</literal> - Velocity uses this
             iterator directly</para>
           </listitem>
 
           <listitem>
-            <para><literal>java.lang.Enumeration</literal> Velocity wrapping
+            <para><literal>java.lang.Enumeration</literal> - Velocity wrapping
             the Enumeration into an Iterator</para>
           </listitem>
         </itemizedlist></para>
@@ -1491,22 +1622,28 @@
         <para>Using an Iterator or Enumeration object directly in a template
         has the side effect that the loop cannot be evaluated multiple times
         because the loop consumes the object that gets iterated. Be especially
-        careful if you use such an object inside a Macro or an included
+        careful if you use such an object inside a Velocimacro or an included
         template.</para>
       </warning>
 
       <para>Velocity provides you with a loop counter reference which contains
       the number of the current iteration of the loop:</para>
 
-      <programlisting>&lt;table&gt;
+      <example id="example-using-the-loop-counter">
+        <title>Using the loop counter</title>
+
+        <programlisting>&lt;table&gt;
   #foreach( $customer in $customerList )
     &lt;tr&gt;&lt;td&gt;$velocityCount&lt;/td&gt;&lt;td&gt;$customer.Name&lt;/td&gt;&lt;/tr&gt;
   #end
 &lt;/table&gt;</programlisting>
+      </example>
 
       <para>The default name for the loop counter and its starting value is
-      specified through runtime properties. By default it starts at 1 and is
-      called <literal>$velocityCount</literal>.</para>
+      specified through runtime settings. By default it starts at 1 and is
+      called <literal>$velocityCount</literal>. If you need these values
+      changed, consult your Java developers and the Velocity Developers
+      Guide.</para>
 
       <programlisting># Default name of the loop counter
 # variable reference.
@@ -1519,7 +1656,7 @@
       <para>The Velocity loop counter variable does support nested loops, so
       the following example would work as expected:</para>
 
-      <example>
+      <example id="example-nested-loops-and-the-loop-counter">
         <title>Nested Loops and the loop counter</title>
 
         <programlisting>#foreach ($category in $allCategories)
@@ -1535,11 +1672,11 @@
       <para>The loop counter is local to its surrounding loop and any inner
       loops hides but not resets it. Please note that it is not possible to
       access the count variable of the outer loop directly inside the inner
-      loop.<footnote>
+      loop<footnote>
           <para>You can assign its value to another variable before entering
           the inner loop using <literal>#set</literal> and access it through
           this variable inside the inner loop.</para>
-        </footnote></para>
+        </footnote>.</para>
 
       <para>To avoid deadlocks and denial of service attacks, it is possible
       to set a maximum allowed number of times that a loop may be executed. By
@@ -1550,23 +1687,71 @@
 directive.foreach.maxloops = -1</programlisting>
     </section>
 
+      <?hard-pagebreak ?>
+
+    <section id="section-stop-template-rendering-stop">
+      <title>Stop template rendering - #stop</title>
+
+      <para>The <literal>#stop</literal> directive stops the rendering of a
+      template. The remaining part of the template after this directive is
+      discarded. The most common usage of this directive is debugging
+      templates<footnote>
+            <para>It is possible to do strange things by using the
+            <literal>#stop</literal> directive inside <literal>#if ... #else
+            ... #end</literal> blocks. As <literal>#stop</literal> only ends
+            the rendering if it is actually encountered, it is possible to
+            skip over the directive.</para>
+          </footnote>.</para>
+
+      <example id="example-using-stop-to-end-template-rendering">
+        <title>Using <literal>#stop</literal> to end template
+        rendering</title>
+
+        <programlisting>This part gets rendered in the output.
+#stop
+This part does not get rendered.</programlisting>
+      </example>
+
+      <para>The <literal>#stop</literal> directive can also be written as
+      <literal>#stop()</literal>.</para>
+
+      <caution>
+        <para>While <literal>#stop</literal> ends the rendering process, it
+        <emphasis>does not</emphasis> affect the template parsing. If you have
+        a syntax error in the VTL code after the <literal>#stop</literal>
+        directive, this error will still be reported.</para>
+      </caution>
+    </section>
+
     <section id="section-loading-resources">
       <title>Loading resources</title>
 
-      <para>In Velocity just as in other rendering techniques like JSP it is
+      <para>In Velocity, just as in other rendering techniques like JSP, it is
       important to build output from multiple input files. For this, you need
       to be able to pull external resources into the rendering process.</para>
 
-      <para>Velocity supports the loading of external files by the #include
-      and #parse directive, which both load external resources into the
-      rendering process of a template.</para>
-
-      <para>Velocity does not allow you to include arbitrary files into your
-      templates for security reasons. All included files will be loaded from
-      ResourceLoaders configured in the Velocity configuration. Please consult
-      the Developers Guide for information on how to do this.</para>
+      <note>
+        <para>For convenience, we will talk about files in the reminder of
+        this chapter. A template needs not to be a file and strictly spoken, a
+        template can be loaded from arbitrary sources including databases.
+        Using files for templates and referring to their names as file pathes
+        with directories is just the most common way.</para>
+      </note>
+
+      <para>Velocity supports the loading of external templates by the
+      <literal>#include</literal> and <literal>#parse</literal> directive,
+      which both load external resources into the rendering process of a
+      template.</para>
+
+      <para>Velocity does not allow you to include arbitrary templates into
+      your templates for security reasons. All included elements will be
+      loaded with a <firstterm>resource loader</firstterm> set up in the
+      Velocity configuration. Please consult the Developers Guide for
+      information on how to do this.</para>
 
-      <section id="section-file-inclusion">
+      <?hard-pagebreak ?>
+
+      <section id="section-file-inclusion-include">
         <title>File inclusion - #include</title>
 
         <para>The <literal>#include</literal> directive allows the template
@@ -1578,7 +1763,7 @@
         <para>Multiple files can be loaded through a single #include
         directive, their names must be separated by commas.</para>
 
-        <example>
+        <example id="example-including-files-into-a-velocity-template">
           <title>Including files into a Velocity Template</title>
 
           <programlisting>## Load the file one.txt into this template
@@ -1593,7 +1778,7 @@
         could be useful for targeting output according to criteria determined
         when the page request is submitted.</para>
 
-        <example>
+        <example id="example-including-a-file-by-a-variable-reference">
           <title>Including a file named by a variable reference</title>
 
           <programlisting>#set ($seasonalgreetings = "christmas.txt")
@@ -1601,7 +1786,7 @@
         </example>
       </section>
 
-      <section id="section-template-inclusion">
+      <section id="section-template-inclusion-parse">
         <title>Template inclusion - #parse</title>
 
         <para>The <literal>#parse</literal> directive works similar to
@@ -1610,7 +1795,7 @@
         will be evaluted. The output will replace the
         <literal>#parse</literal> directive in the importing template.</para>
 
-        <example>
+        <example id="example-including-an-external-template">
           <title>Including an external template</title>
 
           <programlisting>#parse( "one.vm" )</programlisting>
@@ -1627,7 +1812,19 @@
         <literal>#parse</literal> statements referring to templates that in
         turn have <literal>#parse</literal> statements.</para>
 
-        <example>
+        <para>To avoid infinitive recursion, the number of levels is limited
+        through a configuration property. It is not possible to configure an
+        infinite recursion depth. The default maximum number of recursions is
+        20<footnote>
+            <para>As we said, we wanted to make it hard to write templates
+            that contain endless loops. Allowing unlimited recursion would
+            have been too easy.</para>
+          </footnote>.</para>
+
+        <programlisting># Maximum number of #parse levels
+directive.parse.max.depth = 10</programlisting>
+
+        <example id="example-parsing-a-recursive-template">
           <title>Parsing a recursive template</title>
 
           <programlisting>## ########################################
@@ -1671,58 +1868,12 @@
 All done with countdown.vm!</programlisting>
         </example>
 
-        <para>To avoid infinitive recursion, the number of levels is limited
-        through a configuration property. It is not possible to configure an
-        infinite recursion depth. The default maximum number of recursions is
-        20.<footnote>
-            <para>As we said, we wanted to make it hard to write templates
-            that contain endless loops. Allowing recustion would have been too
-            easy.</para>
-          </footnote></para>
-
-        <programlisting># Maximum number of #parse levels
-directive.parse.max.depth = 10</programlisting>
       </section>
     </section>
 
-    <section id="section-stop-template-rendering">
-      <title>Stop template rendering - #stop</title>
-
-      <para>The <literal>#stop</literal> directive stops the rendering of a
-      template. The remaining part of the template after this directive is
-      discarded. The most common usage of this directive is debugging
-      templates.</para>
-
-      <example>
-        <title>Using <literal>#stop</literal> to end template
-        rendering</title>
-
-        <programlisting>This part gets rendered in the output.
-#stop
-This part does not get rendered.</programlisting>
-      </example>
-
-      <para>The <literal>#stop</literal> directive can also be written as
-      <literal>#stop()</literal>.</para>
-
-      <caution>
-        <para>While <literal>#stop</literal> ends the rendering process, it
-        <emphasis>does not</emphasis> affect the template parsing. If you have
-        a syntax error in the VTL code after the <literal>#stop</literal>
-        directive, this error will still be reported.<footnote>
-            <para>It is possible to do strange things by using the
-            <literal>#stop</literal> directive inside <literal>#if ... #else
-            ... #end</literal> blocks. As <literal>#stop</literal> only ends
-            the rendering if it is actually rendered, it is possible to skip
-            over the directive.</para>
-          </footnote></para>
-      </caution>
-
-      <para/>
-    </section>
   </chapter>
 
-  <chapter id="section-relational-and-logical-operators">
+  <chapter id="chapter-operators">
     <title>Operators</title>
 
     <para>Velocity knows a number of relational and logical operators. They
@@ -1733,7 +1884,8 @@
     is roughly equal to the Java notation and a text representation which can
     be used to avoid problems e.g. with XML templates and the
     <literal>&lt;</literal>, <literal>&gt;</literal> and
-    <literal>&amp;&amp;</literal> operators.<example>
+    <literal>&amp;&amp;</literal> operators.<example
+        id="example-using-operators">
         <title>Using operators</title>
 
         <para><programlisting>#set ($a = true)
@@ -1766,7 +1918,7 @@
           <row>
             <entry>equal<footnote>
                 <para>Note that the semantics of the equal operator are
-                slightly different than Java where<literal>==</literal> can
+                slightly different than Java where <literal>==</literal> can
                 only be used to test object equality. In Velocity the
                 equivalent operator can be used to directly compare numbers,
                 strings, or objects. When the objects are of different
@@ -1852,83 +2004,91 @@
         (zero) or the empty String ('') to be equivalent to false. Only the
         boolean value false (primitive oder <literal>Boolean.FALSE</literal>)
         and null are evaluated to false. Everything else evaluates to
-        true.<footnote>
-            <para>This was a conscious decision by the Velocity designers and
+        true.</para><para>This was a conscious decision by the Velocity designers and
             is not likely to change.</para>
-          </footnote></para>
       </caution>Here is a simple example to illustrate how the equivalent
     operator is used.</para>
 
-    <programlisting>#set ($foo = "deoxyribonucleic acid")
+    <example id="example-using-the-equivalent-operator">
+      <title>Using the equivalent operator</title>
+
+      <programlisting>#set ($foo = "deoxyribonucleic acid")
 #set ($bar = "ribonucleic acid")
 
 #if ($foo == $bar)
-  In this case it's clear they aren't equivalent. So...
+  In this case it is clear they aren't equivalent. So...
 #else
   They are not equivalent and this will be the output.
 #end</programlisting>
+    </example>
 
     <para>The text versions of all logical operators can be used to avoid
-    problems with &lt; and &gt; in XML templates.</para>
+    problems with &amp;, &lt;, and &gt; in XML templates.</para>
 
     <section id="section-the-and-operator">
       <title>The AND Operator</title>
 
-      <programlisting>## logical AND
+      <example id="example-using-logical-and">
+        <title>Using logical AND</title>
 
-#if( $foo &amp;&amp; $bar )
+        <programlisting>#if( $this &amp;&amp; $that )
   &lt;strong&gt;This AND that&lt;/strong&gt;
 #end</programlisting>
+      </example>
 
-      <para>The <literal>#if()</literal> directive will only evaluate to true
-      if both <literal>$foo</literal> and <literal>$bar</literal> are true. If
-      <literal>$foo</literal> is false, the expression will evaluate to false;
-      <literal>$bar</literal> will not be evaluated. If
-      <literal>$foo</literal> is true, the Velocity Templating Engine will
-      then check the value of <literal>$bar</literal>; if
-      <literal>$bar</literal> is true, then the entire expression is true and
-      This AND that becomes the output. If <literal>$bar</literal> is false,
-      then there will be no output as the entire expression is false.</para>
+      <para>The <literal>#if</literal> directive will only evaluate to true if
+      both <literal>$this</literal> and <literal>$that</literal> are true. If
+      <literal>$this</literal> is false, the expression will evaluate to
+      false; <literal>$that</literal> will not be evaluated. If
+      <literal>$this</literal> is true, then Velocity will then check the
+      value of <literal>$that</literal>; if <literal>$that</literal> is true,
+      then the entire expression is true and This AND that becomes the output.
+      If <literal>$that</literal> is false, then there will be no output as
+      the entire expression is false.</para>
     </section>
 
-    <section id="the-or-operator">
+    <section id="section-the-or-operator">
       <title>The OR Operator</title>
 
       <para>Logical OR operators work the same way as AND operators, except
       only one of the references need evaluate to true in order for the entire
       expression to be considered true. Consider the following example:</para>
 
-      <programlisting>## logical OR
+      <example id="example-using-logical-or">
+        <title>Using logical OR</title>
 
-#if( $foo || $bar )
+        <programlisting>#if( $this || $that )
   &lt;strong&gt;This OR That&lt;/strong&gt;
 #end</programlisting>
+      </example>
 
-      <para>If <literal>$foo</literal> is true, the Velocity Templating Engine
-      has no need to look at <literal>$bar</literal>; whether
-      <literal>$bar</literal> is true or false, the expression will be true,
-      and This OR That will be output. If <literal>$foo</literal> is false,
-      however, <literal>$bar</literal> must be checked. In this case, if
-      <literal>$bar</literal> is also false, the expression evaluates to false
-      and there is no output. On the other hand, if <literal>$bar</literal> is
-      true, then the entire expression is true, and the output is This OR
-      That</para>
+      <para>If <literal>$this</literal> is true, the Velocity templating
+      engine has no need to look at <literal>$that</literal>; whether
+      <literal>$that</literal> is true or false, the expression will be true,
+      and This OR That will be output. If <literal>$this</literal> is false,
+      however, <literal>$that</literal> must be checked. In this case, if
+      <literal>$that</literal> is also false, the expression evaluates to
+      false and there is no output. On the other hand, if
+      <literal>$that</literal> is true, then the entire expression is true,
+      and the output is This OR That</para>
     </section>
 
-    <section id="the-not-operator">
+    <section id="section-the-not-operator">
       <title>The NOT Operator</title>
 
       <para>With logical NOT operators, there is only one argument:</para>
 
-      <programlisting>##logical NOT
+      <example id="example-using-logical-not">
+        <title>Using logical NOT</title>
 
-#if( !$foo )
+        <programlisting>#if( !$that )
   &lt;strong&gt;NOT that&lt;/strong&gt;
 #end</programlisting>
+      </example>
 
-      <para>Here, the if <literal>$foo</literal> is true, then
-      <literal>!$foo</literal> evaluates to false, and there is no output. If
-      <literal>$foo</literal> is false, then <literal>!$foo</literal>
+      <para>Here, the if <literal>$that</literal> is true, then
+      <literal>!$that</literal> evaluates to false, and there is no output. If
+      <literal>$that</literal> is false, then <literal>!$that</literal>
       evaluates to true and <computeroutput>NOT that</computeroutput> will be
       output. Be careful not to confuse this with the <emphasis>quiet
       reference </emphasis><literal>$!foo</literal>.</para>
@@ -1939,12 +2099,12 @@
     <title>Velocity Macros</title>
 
     <para>The <literal>#macro</literal> directive allows you to name a section
-    of a VTL template and re-insert it multiple times into the template.
-    Velocity macros (or short <firstterm>Velocimacros</firstterm>) can be used
+    of a VTL template and re-insert it multiple times into the template. A
+    Velocity macro (or short <firstterm>Velocimacro</firstterm>) can be used
     in many different scenarios.</para>
 
     <para>In the following example, a Velocimacro is created to save
-    keystrokes and minimizing typographic errors:</para>
+    keystrokes and minimize typographic errors:</para>
 
     <programlisting>#macro( d ) &lt;tr&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt; #end</programlisting>
 
@@ -1955,24 +2115,27 @@
 
     <para>When this template is rendered, Velocity replaces
     <literal>#d()</literal> with the HTML table row containing a single, empty
-    cell defined above. Using a macro in a template is called <firstterm>macro
-    invocation</firstterm>.</para>
+    cell defined above. Using a Velocimacro in a template is called
+    <firstterm>macro invocation</firstterm>.</para>
 
-    <para>Velocimacros start with the <literal>#macro</literal> directive and
-    are ended with <literal>#end</literal>. The enclosed block is the
-    <firstterm>macro body</firstterm>. Whenever a Velocimacro is invoked, its
-    body is inserted in the template. It is rendered at every invokation
-    through the templating engine, with the invocation arguments replacing the
-    arguments in the macro definition.</para>
+    <para>A Velocimacro definition starts with the <literal>#macro</literal>
+    directive and are ended with <literal>#end</literal>. The enclosed block
+    is the <firstterm>macro body</firstterm>. Whenever a Velocimacro is
+    invoked, its body is inserted in the template. It is rendered at every
+    invokation through the templating engine, with the invocation arguments
+    replacing the arguments in the Velocimacro definition.</para>
 
     <para>A Velocimacro can take any number of arguments including zero, but
     when it is invoked, it must be called with exactly the same number of
-    arguments with which it was defined.</para>
+    arguments that it was defined with.</para>
 
     <para>Here is a Velocimacro that takes two arguments, a color and a list
     of objects:</para>
 
-    <programlisting>#macro( tablerows $color $values )
+    <example id="example-macro-with-two-arguments">
+      <title>A macro that takes two arguments</title>
+
+      <programlisting>#macro( tablerows $color $values )
   #foreach( $value in $values )
     &lt;tr&gt;&lt;td bgcolor=$color&gt;$value&lt;/td&gt;&lt;/tr&gt;
   #end
@@ -1984,12 +2147,13 @@
 &lt;table&gt;
   #tablerows( $color $greatlakes )
 &lt;/table&gt;</programlisting>
+    </example>
 
-    <para>The <literal>tablerows</literal> macro takes exactly two arguments.
-    The first argument takes the place of <literal>$color</literal>, and the
-    second argument takes the place of <literal>$values</literal>. Anything
-    that can be put into a VTL template can go into the body of a
-    Velocimacro.</para>
+    <para>The <literal>tablerows</literal> Velocimacro takes exactly two
+    arguments. The first argument takes the place of
+    <literal>$color</literal>, and the second argument takes the place of
+    <literal>$values</literal>. Anything that can be put into a VTL template
+    can go into the body of a Velocimacro.</para>
 
     <para>Notice that <literal>$greatlakes</literal> takes the place of
     <literal>$values</literal>. When this template is rendered, the following
@@ -2003,15 +2167,16 @@
 &lt;tr&gt;&lt;td bgcolor="blue"&gt;Ontario&lt;/td&gt;&lt;/tr&gt;
 &lt;/table&gt;</programlisting>
 
-    <para>In the example above, the <literal>#tablerows</literal> macro was
-    defined <firstterm>inline</firstterm>. Velocimacros can be defined
-    <emphasis>inline</emphasis> or <emphasis>global</emphasis>. An inline
-    macro is only visible in the template where it is defined, a global macro
+    <para>In the example above, the <literal>#tablerows</literal> Velocimacro
+    was defined as an <firstterm>inline macro</firstterm>. Another way to
+    declare a macro is in a <firstterm>Velocimacro library</firstterm>, it is
+    then called a <firstterm>global macro</firstterm>. An inline Velocimacro
+    is only visible in the template where it is defined, a global Velocimacro
     is accessible from all templates. Global definitions must be done in a a
     Velocimacro template library, which is a template file that contains the
     macros and they must be referenced explicitly through the Velocity
-    configuration. Please see the Velocity reference guide for more
-    information on how to define and load a Macro library.</para>
+    configuration. Please see the Velocity Reference Guide for more
+    information on how to define and load a macro library.</para>
 
     <para>If the <literal>#tablerows($color $values)</literal> Velocimacro is
     defined a Velocimacro template library, it could be in any template. In
@@ -2024,7 +2189,7 @@
   #tablerows( $cellbgcol $fruits )
 &lt;/table&gt;</programlisting>
 
-    <para>When rendering this template, Velocitywould find the
+    <para>When rendering this template, Velocity would find the
     <literal>#tablerows</literal> Velocimacro in a template library (defined
     in the Velocity configuration) and generate the following output:</para>
 
@@ -2035,38 +2200,40 @@
   &lt;tr&gt;&lt;td bgcolor="white"&gt;strawberry&lt;/td&gt;&lt;/tr&gt;
 &lt;/table&gt;</programlisting>
 
+      <?hard-pagebreak ?>
+
     <section id="section-velocimacro-arguments">
       <title>Velocimacro Arguments</title>
 
       <para>Velocimacros can take as arguments any of the following VTL
       elements:</para>
 
-      <itemizedlist spacing="compact">
+      <para><itemizedlist spacing="compact">
         <listitem>
-          <para>Reference : anything that starts with '$'</para>
+          <para>A reference, starting with <literal>$</literal></para>
         </listitem>
 
         <listitem>
-          <para>String literal : something like "$foo" or 'hello'</para>
+          <para>A String literal, enclosed in single or double quotes</para>
         </listitem>
 
         <listitem>
-          <para>Number literal : 1, 2 etc</para>
+          <para>A Number literal (1, 2, 3 etc.)</para>
         </listitem>
 
         <listitem>
-          <para>IntegerRange : [ 1..2] or [$foo .. $bar]</para>
+          <para>An IntegerRange ([ 1..2] or [$start .. $end])</para>
         </listitem>
 
         <listitem>
-          <para>ObjectArray : [ "a", "b", "c"]</para>
+          <para>An ObjectArray ([ "a", "b", "c"])</para>
         </listitem>
 
         <listitem>
-          <para>The words true and false: boolean values for true and
-          false</para>
+          <para><literal>true</literal> and <literal>false</literal> for
+          boolean values representing true and false</para>
         </listitem>
-      </itemizedlist>
+      </itemizedlist></para>
 
       <para>When passing references as arguments to Velocimacros, please note
       that references are passed <emphasis>by name</emphasis>. This means that
@@ -2074,11 +2241,15 @@
       This feature allows you to pass references with method calls and have
       the method called at each use:</para>
 
-      <programlisting>#macro( callme $a )
+      <example id="example-passing-parameters-by-name">
+        <title>Passing parameters by name</title>
+
+        <programlisting>#macro( callme $a )
   $a $a $a
 #end
 
 #callme( $foo.bar() )</programlisting>
+      </example>
 
       <para>results in the method <literal>bar()</literal> of the reference
       <literal>$foo</literal> being called 3 times.</para>
@@ -2086,26 +2257,32 @@
       <caution>
         <para>If you are used to the behaviour of method or procedure calls in
         programming languages like Java or C, please be sure to fully
-        understand the implications of the passing by name of references.
+        understand the implications of <emphasis>passing by name</emphasis>.
         Unlike these programming languages, the reference is not evaluated at
-        macro invocation time but at every occurence inside the macro. Don't
-        treat macros as procedures or methods!</para>
+        macro invocation time but at every occurence inside the Velocimacro.
+        Don't treat Velocimacros as procedures or methods!</para>
       </caution>
 
       <para>The easiest way to avoid any gotchas is not passing any stateful
       object into a Velocimacro. This can be done by assigning the result of a
       method invocation to a new reference:</para>
 
-      <programlisting>#set( $myval = $foo.bar() )
+      <example id="example-resolving-a-stateful-object">
+        <title>Resolving a stateful object before macro invocation</title>
+
+        <programlisting>#set( $myval = $foo.bar() )
 #callme( $myval )</programlisting>
+      </example>
     </section>
 
+      <?hard-pagebreak ?>
+
     <section id="section-velocimacro-properties">
       <title>Velocimacro Properties</title>
 
       <para>There are a number of properties in the Velocity configuration
-      that influence the behaviour of macros. A complete list of all
-      configuration options is in the Velocity Reference guide.</para>
+      that influence the behaviour of the Velocimacros. A complete list of all
+      configuration options is in the Velocity Reference Guide.</para>
 
       <variablelist>
         <varlistentry>
@@ -2139,9 +2316,9 @@
             the user to specify if a Velocimacro defined inline in a template
             can replace a globally defined template, one that was loaded on
             startup via the <literal>velocimacro.library</literal> property.
-            The default, <literal>false</literal>, prevents Velocimacros
-            defined inline in a template from replacing those defined in the
-            template libraries loaded at startup.</para>
+            The default, false, prevents Velocimacros defined inline in a
+            template from replacing those defined in the template libraries
+            loaded at startup.</para>
           </listitem>
         </varlistentry>
 
@@ -2177,87 +2354,240 @@
 
           <listitem>
             <para>This property controls Velocimacro library autoloading. The
-            default value is <literal>false</literal>. When set to
-            <literal>true</literal> the source Velocimacro library for an
-            invoked Velocimacro will be checked for changes, and reloaded if
-            necessary. This allows you to change and test Velocimacro
-            libraries without having to restart your application or servlet

[... 595 lines stripped ...]