Commits

fero14041 committed 2637ece

Fix some various typos in documentation:
fix misspelled words, remove line ending spaces, change ``-`` to ``--``,
add some ``'`` between subject and 'to be' verb (e.g. "it's", "i'm"),
add some ending dots to sentences, change some letters "capitalness", etc.

Comments (0)

Files changed (15)

doc/build/caching.rst

 .. sourcecode:: mako
 
     <%page cached="True"/>
- 
+
     template text
- 
+
 The above template, after being executed the first time, will
 store its content within a cache that by default is scoped
 within memory. Subsequent calls to the template's :meth:`~.Template.render`
 cache is garbage collected along with the template.
 
 By default, caching requires that the `Beaker <http://beaker.readthedocs.org/>`_ package be installed on the
-system, however the mechanism of caching can be customized to use 
-any third party or user defined system - see :ref:`cache_plugins`.
+system, however the mechanism of caching can be customized to use
+any third party or user defined system -- see :ref:`cache_plugins`.
 
-In addition to being available on the ``<%page>`` tag, the caching flag and all 
+In addition to being available on the ``<%page>`` tag, the caching flag and all
 its options can be used with the ``<%def>`` tag as well:
 
 .. sourcecode:: mako
 Cache arguments
 ================
 
-Mako has two cache arguments available on tags that are 
-available in all cases.   The rest of the arguments 
+Mako has two cache arguments available on tags that are
+available in all cases.   The rest of the arguments
 available are specific to a backend.
 
-The two generic tags are:
+The two generic tags arguments are:
 
-* ``cached="True"`` - enable caching for this ``<%page>``, 
+* ``cached="True"`` - enable caching for this ``<%page>``,
   ``<%def>``, or ``<%block>``.
 * ``cache_key`` - the "key" used to uniquely identify this content
   in the cache.   Usually, this key is chosen automatically
   For example, here's a page
   that caches any page which inherits from it, based on the
   filename of the calling template:
- 
+
   .. sourcecode:: mako
 
      <%page cached="True" cache_key="${self.filename}"/>
 
      ${next.body()}
- 
+
      ## rest of template
 
-On a :class:`.Template` or :class:`.TemplateLookup`, the 
+On a :class:`.Template` or :class:`.TemplateLookup`, the
 caching can be configured using these arguments:
 
 * ``cache_enabled`` - Setting this
   e.g.::
 
     lookup = TemplateLookup(
-                    directories='/path/to/templates', 
+                    directories='/path/to/templates',
                     cache_enabled = False
                     )
 
 * ``cache_impl`` - The string name of the cache backend
-  to use.   This defaults to ``beaker``, which has historically
-  been the only cache backend supported by Mako.  
+  to use.   This defaults to ``'beaker'``, which has historically
+  been the only cache backend supported by Mako.
   New in 0.6.0.
 
   For example, here's how to use the upcoming
   backend::
 
     lookup = TemplateLookup(
-                    directories='/path/to/templates', 
+                    directories='/path/to/templates',
                     cache_impl = 'dogpile.cache',
                     cache_args = {'regions':my_dogpile_regions}
                     )
 
 * ``cache_args`` - A dictionary of cache parameters that
-  will be consumed by the cache backend.   See 
+  will be consumed by the cache backend.   See
   :ref:`beaker_backend` for examples.  New in 0.6.0.
 
 Backend-Specific Cache Arguments
 --------------------------------
 
-The ``<%page>``, ``<%def>``, and ``<%block>`` tags 
+The ``<%page>``, ``<%def>``, and ``<%block>`` tags
 accept any named argument that starts with the prefix ``"cache_"``.
 Those arguments are then packaged up and passed along to the
 underlying caching implementation, minus the ``"cache_"`` prefix.
 The actual arguments understood are determined by the backend.
 
 * :ref:`beaker_backend` - Includes arguments understood by
-  Beaker
-* :ref:`mako_plugin` - Includes arguments understood by 
+  Beaker.
+* :ref:`mako_plugin` - Includes arguments understood by
   dogpile.cache.
 
 .. _beaker_backend:
 
 When using Beaker, new implementations will want to make usage
 of **cache regions** so that cache configurations can be maintained
-externally to templates.  These configurations live under 
-named "regions" that can be referred to within templates themselves.  
+externally to templates.  These configurations live under
+named "regions" that can be referred to within templates themselves.
 Support for Beaker cache regions is new in Mako 0.6.0.
 
 For example, suppose we would like two regions.  One is a "short term"
 region that will store content in a memory-based dictionary,
 expiring after 60 seconds.   The other is a Memcached region,
 where values should expire in five minutes.   To configure
-our :class:`.TemplateLookup`, first we get a handle to a 
+our :class:`.TemplateLookup`, first we get a handle to a
 :class:`beaker.cache.CacheManager`::
 
     from beaker.cache import CacheManager
     lookup = TemplateLookup(
                     directories=['/path/to/templates'],
                     module_directory='/path/to/modules',
-                    cache_impl = 'beaker',
-                    cache_args = {
+                    cache_impl='beaker',
+                    cache_args={
                         'manager':manager
                     }
             )
 
 The Beaker backend also works without regions.   There are a
 variety of arguments that can be passed to the ``cache_args``
-dictionary, which are also allowable in templates via the 
+dictionary, which are also allowable in templates via the
 ``<%page>``, ``<%block>``,
 and ``<%def>`` tags specific to those sections.   The values
-given override those specified at the  :class:`.TemplateLookup` 
-or :class:`.Template` level.  
+given override those specified at the  :class:`.TemplateLookup`
+or :class:`.Template` level.
 
-With the possible exception 
+With the possible exception
 of ``cache_timeout``, these arguments are probably better off
 staying at the template configuration level.  Each argument
 specified as ``cache_XYZ`` in a template tag is specified
   cached data.  After this timeout, the content is re-generated
   on the next call.  Available as ``timeout`` in the ``cache_args``
   dictionary.
-* ``cache_type`` - type of caching. ``memory``, ``file``, ``dbm``, or
-  ``ext:memcached`` (note that  the string ``memcached`` is
-  also accepted by the Mako plugin, though not by Beaker itself).  
+* ``cache_type`` - type of caching. ``'memory'``, ``'file'``, ``'dbm'``, or
+  ``'ext:memcached'`` (note that  the string ``memcached`` is
+  also accepted by the dogpile.cache Mako plugin, though not by Beaker itself).
   Available as ``type`` in the ``cache_args`` dictionary.
 * ``cache_url`` - (only used for ``memcached`` but required) a single
   IP address or a semi-colon separated list of IP address of
   memcache servers to use.  Available as ``url`` in the ``cache_args``
   dictionary.
-* ``cache_dir`` - In the case of the ``file`` and ``dbm`` cache types,
+* ``cache_dir`` - in the case of the ``'file'`` and ``'dbm'`` cache types,
   this is the filesystem directory with which to store data
   files. If this option is not present, the value of
   ``module_directory`` is used (i.e. the directory where compiled
 `dogpile.cache`_ is a new replacement for Beaker.   It provides
 a modernized, slimmed down interface and is generally easier to use
 than Beaker.   As of this writing it has not yet been released.  dogpile.cache
-includes its own Mako cache plugin - see :ref:`mako_plugin` in the
+includes its own Mako cache plugin -- see :ref:`mako_plugin` in the
 dogpile.cache documentation.
 
 Programmatic Cache Access
     <%
         local.cache.set("somekey", type="memory", "somevalue")
     %>
- 
+
 Above, the cache associated with the ``local`` namespace is
 accessed and a key is placed within a memory cache.
 
 .. sourcecode:: python
 
     template = lookup.get_template('/sometemplate.html')
- 
+
     # invalidate the "body" of the template
     template.cache.invalidate_body()
- 
+
     # invalidate an individual def
     template.cache.invalidate_def('somedef')
- 
+
     # invalidate an arbitrary key
     template.cache.invalidate('somekey')
 
 
     template.cache.impl.do_something_special()
 
-Note that using implementation-specific methods will mean you can't 
-swap in a different kind of :class:`.CacheImpl` implementation at a 
+Note that using implementation-specific methods will mean you can't
+swap in a different kind of :class:`.CacheImpl` implementation at a
 later time.
 
 .. _cache_plugins:
 The mechanism used by caching can be plugged in
 using a :class:`.CacheImpl` subclass.    This class implements
 the rudimental methods Mako needs to implement the caching
-API.   Mako includes the :class:`.BeakerCacheImpl` class to 
+API.   Mako includes the :class:`.BeakerCacheImpl` class to
 provide the default implementation.  A :class:`.CacheImpl` class
-is acquired by Mako using a ``pkg_resources`` entrypoint, using 
+is acquired by Mako using a ``pkg_resources`` entrypoint, using
 the name given as the ``cache_impl`` argument to :class:`.Template`
 or :class:`.TemplateLookup`.    This entry point can be
 installed via the standard setuptools/``setup()`` procedure, underneath
 
         def set(self, key, value, **kwargs):
             self._cache[key] = value
- 
+
         def get(self, key, **kwargs):
             return self._cache.get(key)
- 
+
         def invalidate(self, key, **kwargs):
             self._cache.pop(key, None)
 
 
 Enabling the above plugin in a template would look like::
 
-    t = Template("mytemplate", 
-                    file="mytemplate.html", 
+    t = Template("mytemplate",
+                    file="mytemplate.html",
                     cache_impl='simple')
 
 Guidelines for writing cache plugins
 ------------------------------------
 
-* The :class:`.CacheImpl` is created on a per-:class:`.Template` basis.  The 
+* The :class:`.CacheImpl` is created on a per-:class:`.Template` basis.  The
   class should ensure that only data for the parent :class:`.Template` is
   persisted or returned by the cache methods.    The actual :class:`.Template`
   is available via the ``self.cache.template`` attribute.   The ``self.cache.id``
-  attribute, which is essentially the unique modulename of the template, is 
+  attribute, which is essentially the unique modulename of the template, is
   a good value to use in order to represent a unique namespace of keys specific
   to the template.
-* Templates only use the :meth:`.CacheImpl.get_or_create()` method 
+* Templates only use the :meth:`.CacheImpl.get_or_create()` method
   in an implicit fashion.  The :meth:`.CacheImpl.set`,
-  :meth:`.CacheImpl.get`, and :meth:`.CacheImpl.invalidate` methods are 
+  :meth:`.CacheImpl.get`, and :meth:`.CacheImpl.invalidate` methods are
   only used in response to direct programmatic access to the corresponding
   methods on the :class:`.Cache` object.
 * :class:`.CacheImpl` will be accessed in a multithreaded fashion if the
   :class:`.Template` itself is used multithreaded.  Care should be taken
   to ensure caching implementations are threadsafe.
-* A library like `Dogpile <http://pypi.python.org/pypi/Dogpile>`_, which
+* A library like `Dogpile <http://pypi.python.org/pypi/dogpile.core>`_, which
   is a minimal locking system derived from Beaker, can be used to help
   implement the :meth:`.CacheImpl.get_or_create` method in a threadsafe
   way that can maximize effectiveness across multiple threads as well
   key method used by templates.
 * All arguments passed to ``**kw`` come directly from the parameters
   inside the ``<%def>``, ``<%block>``, or ``<%page>`` tags directly,
-  minus the ``"cache_"`` prefix, as strings, with the exception of 
-  the argument ``cache_timeout``, which is passed to the plugin 
+  minus the ``"cache_"`` prefix, as strings, with the exception of
+  the argument ``cache_timeout``, which is passed to the plugin
   as the name ``timeout`` with the value converted to an integer.
-  Arguments present in ``cache_args`` on :class:`.Template` or 
+  Arguments present in ``cache_args`` on :class:`.Template` or
   :class:`.TemplateLookup` are passed directly, but are superseded
   by those present in the most specific template tag.
 * The directory where :class:`.Template` places module files can
 
 .. autoclass:: mako.cache.CacheImpl
     :members:
-    :show-inheritance:    
+    :show-inheritance:
 
 .. autofunction:: mako.cache.register_plugin
 

doc/build/defs.rst

 ===============
 
 ``<%def>`` and ``<%block>`` are two tags that both demarcate any block of text
-and/or code.   They both exist within generated Python as a callable function, 
+and/or code.   They both exist within generated Python as a callable function,
 i.e., a Python ``def``.   They differ in their scope and calling semantics.
 Whereas ``<%def>`` provides a construct that is very much like a named Python
 ``def``, the ``<%block>`` is more layout oriented.
     the def:  ${hello()}
 
 If the ``<%def>`` is not nested inside of another ``<%def>``,
-its known as a **top level def** and can be accessed anywhere in
+it's known as a **top level def** and can be accessed anywhere in
 the template, including above where it was defined.
 
 All defs, top level or not, have access to the current
 .. sourcecode:: mako
 
     Hello there ${username}, how are ya.  Lets see what your account says:
- 
+
     ${account()}
 
     <%def name="account()">
         Account for ${username}:<br/>
- 
+
         % for row in accountdata:
             Value: ${row}<br/>
         % endfor
 .. sourcecode:: mako
 
     ${account(accountname='john')}
- 
+
     <%def name="account(accountname, type='regular')">
-        account name: ${accountname}, type ${type}
+        account name: ${accountname}, type: ${type}
     </%def>
 
 When you declare an argument signature for your def, they are
 which evaluate to ``UNDEFINED`` if you reference a name that
 does not exist.
 
-Calling defs from Other Files 
+Calling defs from Other Files
 -----------------------------
 
-Top level ``<%defs>`` are **exported** by your template's
+Top level ``<%def>``\ s are **exported** by your template's
 module, and can be called from the outside; including from other
 templates, as well as normal Python code. Calling a ``<%def>``
 from another template is something like using an ``<%include>``
-- except you are calling a specific function within the
+-- except you are calling a specific function within the
 template, not the whole template.
 
 The remote ``<%def>`` call is also a little bit like calling
 Calling defs programmatically
 -----------------------------
 
-You can call def's programmatically from any :class:`.Template` object
+You can call defs programmatically from any :class:`.Template` object
 using the :meth:`~.Template.get_def()` method, which returns a :class:`.DefTemplate`
 object. This is a :class:`.Template` subclass which the parent
 :class:`.Template` creates, and is usable like any other template:
 .. sourcecode:: python
 
     from mako.template import Template
- 
+
     template = Template("""
         <%def name="hi(name)">
             hi ${name}!
         </%def>
- 
+
         <%def name="bye(name)">
             bye ${name}!
         </%def>
     """)
- 
+
     print template.get_def("hi").render(name="ed")
     print template.get_def("bye").render(name="ed")
- 
 
 Defs within Defs
 ----------------
         <%def name="subdef()">
             a sub def
         </%def>
- 
-        im the def, and the subcomponent is ${subdef()}
+
+        i'm the def, and the subcomponent is ${subdef()}
     </%def>
 
 Just like Python, names that exist outside the inner ``<%def>``
     %>
     <%def name="somedef()">
         ## error !
-        somedef, x is ${x} 
+        somedef, x is ${x}
         <%
-            x = 27 
+            x = 27
         %>
     </%def>
 
 content (or multiple blocks) that can be used by the def being
 called. The main point of such a call is to create custom,
 nestable tags, just like any other template language's
-custom-tag creation system - where the external tag controls the
+custom-tag creation system -- where the external tag controls the
 execution of the nested tags and can communicate state to them.
 Only with Mako, you don't have to use any external Python
 modules, you can define arbitrarily nestable tags right in your
 To achieve this, the target def is invoked using the form
 ``<%namepacename:defname>`` instead of the normal ``${}``
 syntax. This syntax, introduced in Mako 0.2.3, is functionally
-equivalent another tag known as ``call``, which takes the form
+equivalent to another tag known as ``%call``, which takes the form
 ``<%call expr='namespacename.defname(args)'>``. While ``%call``
 is available in all versions of Mako, the newer style is
 probably more familiar looking. The ``namespace`` portion of the
 call is the name of the **namespace** in which the def is
-defined - in the most simple cases, this can be ``local`` or
+defined -- in the most simple cases, this can be ``local`` or
 ``self`` to reference the current template's namespace (the
 difference between ``local`` and ``self`` is one of inheritance
-- see :ref:`namespaces_builtin` for details).
+-- see :ref:`namespaces_builtin` for details).
 
 When the target def is invoked, a variable ``caller`` is placed
 in its context which contains another namespace containing the
             </td></tr>
         </table>
     </%def>
- 
+
     <%self:buildtable>
         I am the table body.
     </%self:buildtable>
- 
+
 This produces the output (whitespace formatted):
 
 .. sourcecode:: html
             ${caller.body()}
         % endfor
     </%def>
- 
+
     <%self:lister count="${3}">
         hi
     </%self:lister>
- 
+
 Produces:
- 
+
 .. sourcecode:: html
 
     hi
 remains as an integer.
 
 A custom "conditional" tag:
- 
+
 .. sourcecode:: mako
 
     <%def name="conditional(expression)">
     </%def>
 
     <%self:conditional expression="${4==4}">
-        im the result
+        i'm the result
     </%self:conditional>
 
 Produces:
 
 .. sourcecode:: html
 
-    im the result
+    i'm the result
 
 But that's not all. The ``body()`` function also can handle
 arguments, which will augment the local namespace of the body
     <%self:layoutdata somedata="${[[1,2,3],[4,5,6],[7,8,9]]}" args="col">\
     Body data: ${col}\
     </%self:layoutdata>
- 
+
 Produces:
 
 .. sourcecode:: html
            <td>Body data: 9</td>
        </tr>
     </table>
- 
+
 You don't have to stick to calling just the ``body()`` function.
 The caller can define any number of callables, allowing the
 ``<%call>`` tag to produce whole layouts:
             <div class="header">
                 ${caller.header()}
             </div>
+
             <div class="sidebar">
                 ${caller.sidebar()}
             </div>
+
             <div class="content">
                 ${caller.body()}
             </div>
                 <li>sidebar 2</li>
             </ul>
         </%def>
- 
+
             this is the body
     </%self:layout>
- 
+
 The above layout would produce:
 
 .. sourcecode:: html
         </body>
     </html>
 
-So in fact the above block has absolutely no effect.   Its usefulness comes when we start
+So in fact the above block has absolutely no effect.  Its usefulness comes when we start
 using modifiers.  Such as, we can apply a filter to our block:
 
 .. sourcecode:: mako
     </body>
     </html>
 
-The above example has two named blocks "``header``" and "``title``", both of which can be referred to 
-by an inheriting template.  A detailed walkthrough of this usage can be found at :ref:`inheritance_toplevel`.
+The above example has two named blocks "``header``" and "``title``", both of which can be referred to
+by an inheriting template. A detailed walkthrough of this usage can be found at :ref:`inheritance_toplevel`.
 
-Note above that named blocks don't have any argument declaration the way defs do.   They still implement themselves
+Note above that named blocks don't have any argument declaration the way defs do. They still implement themselves
 as Python functions, however, so they can be invoked additional times beyond their initial definition:
 
 .. sourcecode:: mako
 To keep things sane, named blocks have restrictions that defs do not:
 
 * The ``<%block>`` declaration cannot have any argument signature.
-* The name of a ``<%block>`` can only be defined once in a template - an error is raised if two blocks of the same
-  name occur anywhere in a single template, regardless of nesting.  A similar error is raised if a top level def 
+* The name of a ``<%block>`` can only be defined once in a template -- an error is raised if two blocks of the same
+  name occur anywhere in a single template, regardless of nesting.  A similar error is raised if a top level def
   shares the same name as that of a block.
 * A named ``<%block>`` cannot be defined within a ``<%def>``, or inside the body of a "call", i.e.
-  ``<%call>`` or ``<%namespacename:defname>`` tag.   Anonymous blocks can, however.
+  ``<%call>`` or ``<%namespacename:defname>`` tag.  Anonymous blocks can, however.
 
 Using page arguments in named blocks
 -------------------------------------
 variable is available both in the main body as well as the
 ``post_prose`` block.
 
-Similarly, the ``**pageargs`` variable is present, in named blocks only, 
+Similarly, the ``**pageargs`` variable is present, in named blocks only,
 for those arguments not explicit in the ``<%page>`` tag:
 
 .. sourcecode:: mako

doc/build/filtering.rst

 * ``u`` : URL escaping, provided by
   ``urllib.quote_plus(string.encode('utf-8'))``
 * ``h`` : HTML escaping, provided by
-  ``markupsafe.escape(string)`` (new as of 0.3.4 - prior
+  ``markupsafe.escape(string)`` (new as of 0.3.4 -- prior
   versions use ``cgi.escape(string, True)``)
 * ``x`` : XML escaping
 * ``trim`` : whitespace trimming, provided by ``string.strip()``
 * ``entity`` : produces HTML entity references for applicable
   strings, derived from ``htmlentitydefs``
 * ``unicode`` (``str`` on Python 3): produces a Python unicode
-  string (this function is applied by default).
-* ``decode.<some encoding>`` : decode input into a Python
+  string (this function is applied by default)
+* ``decode.<some encoding>``: decode input into a Python
   unicode with the specified encoding
 * ``n`` : disable all default filtering; only filters specified
   in the local expression tag will be applied.
 returns the filtered result. The expressions after the ``|``
 operator draw upon the local namespace of the template in which
 they appear, meaning you can define escaping functions locally:
- 
+
 .. sourcecode:: mako
 
     <%!
         def myescape(text):
             return "<TAG>" + text + "</TAG>"
     %>
- 
-    Heres some tagged text: ${"text" | myescape}
- 
+
+    Here's some tagged text: ${"text" | myescape}
+
 Or from any Python module:
 
 .. sourcecode:: mako
     <%!
         import myfilters
     %>
- 
-    Heres some tagged text: ${"text" | myfilters.tagfilter}
- 
+
+    Here's some tagged text: ${"text" | myfilters.tagfilter}
+
 A page can apply a default set of filters to all expression tags
 using the ``expression_filter`` argument to the ``%page`` tag:
 
 .. sourcecode:: mako
 
     <%page expression_filter="h"/>
- 
+
     Escaped text:  ${"<html>some html</html>"}
- 
+
 Result:
 
 .. sourcecode:: html
 
 .. _filtering_default_filters:
 
-The default_filters Argument 
+The default_filters Argument
 ----------------------------
 
 In addition to the ``expression_filter`` argument, the
 .. sourcecode:: python
 
     t = TemplateLookup(directories=['/tmp'], default_filters=[])
- 
+
 Any string name can be added to ``default_filters`` where it
 will be added to all expressions as a filter. The filters are
 applied from left to right, meaning the leftmost filter is
 .. sourcecode:: python
 
     t = Template(templatetext, default_filters=['unicode', 'myfilter'])
- 
+
 To ease the usage of ``default_filters`` with custom filters,
 you can also add imports (or other code) to all templates using
 the ``imports`` argument:
 
 .. sourcecode:: python
 
-    t = TemplateLookup(directories=['/tmp'], 
-        default_filters=['unicode', 'myfilter'], 
+    t = TemplateLookup(directories=['/tmp'],
+        default_filters=['unicode', 'myfilter'],
         imports=['from mypackage import myfilter'])
- 
+
 The above will generate templates something like this:
 
 .. sourcecode:: python
 
 In all cases the special ``n`` filter, used locally within an
 expression, will **disable** all filters declared in the
-``<%page>`` tag as well ``default_filters``. Such as:
+``<%page>`` tag as well as in ``default_filters``. Such as:
 
 .. sourcecode:: mako
 
     ${'myexpression' | n}
 
-Will render ``myexpression`` with no filtering of any kind, and
+will render ``myexpression`` with no filtering of any kind, and:
 
 .. sourcecode:: mako
 
-    ${'myexpression' | n, trim}
- 
-will render ``myexpression`` using the ``trim`` filter only. 
+    ${'myexpression' | n,trim}
+
+will render ``myexpression`` using the ``trim`` filter only.
 
 Filtering Defs and Blocks
 ==========================
     <%def name="foo()" filter="h, trim">
         <b>this is bold</b>
     </%def>
- 
+
 When the filter attribute is applied to a def as above, the def
 is automatically **buffered** as well. This is described next.
 
 .. sourcecode:: mako
 
     ${" results " + somedef() + " more results "}
- 
+
 If the ``somedef()`` function produced the content "``somedef's
 results``", the above template would produce this output:
 
 .. sourcecode:: html
 
     somedef's results results more results
- 
+
 This is because ``somedef()`` fully executes before the
 expression returns the results of its concatenation; the
 concatenation in turn receives just the empty string as its
     <%def name="somedef()" buffered="True">
         somedef's results
     </%def>
- 
+
 The above definition will generate code similar to this:
 
 .. sourcecode:: python
         finally:
             buf = context.pop_buffer()
         return buf.getvalue()
- 
+
 So that the content of ``somedef()`` is sent to a second buffer,
 which is then popped off the stack and its value returned. The
 speed hit inherent in buffering the output of a def is also
 .. sourcecode:: mako
 
     ${" results " + capture(somedef) + " more results "}
- 
+
 Note that the first argument to the ``capture`` function is
 **the function itself**, not the result of calling it. This is
 because the ``capture`` function takes over the job of actually
 .. sourcecode:: mako
 
     ${capture(somedef, 17, 'hi', use_paging=True)}
- 
+
 The above call is equivalent to the unbuffered call:
 
 .. sourcecode:: mako
 
     ${somedef(17, 'hi', use_paging=True)}
- 
+
 Decorating
 ===========
 
                 return ''
             return decorate
     %>
- 
+
     <%def name="foo()" decorator="bar">
         this is foo
     </%def>
- 
+
     ${foo()}
- 
+
 The above template will return, with more whitespace than this,
 ``"BAR this is foo BAR"``. The function is the render callable
 itself (or possibly a wrapper around it), and by default will
 
 The decorator can be used with top-level defs as well as nested
 defs, and blocks too. Note that when calling a top-level def from the
-``Template`` api, i.e. ``template.get_def('somedef').render()``,
+``Template`` API, i.e. ``template.get_def('somedef').render()``,
 the decorator has to write the output to the ``context``, i.e.
 as in the first example. The return value gets discarded.

doc/build/index.rst

 
 .. toctree::
     :maxdepth: 2
- 
+
     usage
     syntax
     defs
     filtering
     unicode
     caching
- 
+
 Indices and tables
 ------------------
 

doc/build/inheritance.rst

 Inheritance
 ===========
 
-.. note::  Most of the inheritance examples here take advantage of a feature that's 
-  new in Mako as of version 0.4.1 called the "block".  This tag is very similar to 
+.. note::  Most of the inheritance examples here take advantage of a feature that's
+  new in Mako as of version 0.4.1 called the "block".  This tag is very similar to
   the "def" tag but is more streamlined for usage with inheritance.  Note that
-  all of the examples here which use blocks can also use defs instead.   Constrasting
+  all of the examples here which use blocks can also use defs instead.  Contrasting
   usages will be illustrated.
 
 Using template inheritance, two or more templates can organize
 
     ## index.html
     <%inherit file="base.html"/>
- 
+
     <%block name="header">
         this is some header content
     </%block>
- 
+
     this is the body content.
- 
+
 And ``base.html``, the inherited template:
 
 .. sourcecode:: mako
             <div class="header">
                 <%block name="header"/>
             </div>
- 
+
             ${self.body()}
- 
+
             <div class="footer">
                 <%block name="footer">
                     this is the footer
     </html>
 
 Here is a breakdown of the execution:
- 
+
 * When ``index.html`` is rendered, control immediately passes to
   ``base.html``.
 * ``base.html`` then renders the top part of an HTML document,
   then invokes the ``<%block name="header">`` block.  It invokes the
-  underlying ``header()`` function off of a built in namespace
+  underlying ``header()`` function off of a built-in namespace
   called ``self`` (this namespace was first introduced in the
   Namespaces chapter in :ref:`namespace_self`). Since
   ``index.html`` is the topmost template and also defines a block
-  called ``header``, its this ``header`` block that ultimately gets
-  executed - instead of the one that's present in ``base.html``.
+  called ``header``, it's this ``header`` block that ultimately gets
+  executed -- instead of the one that's present in ``base.html``.
 * Control comes back to ``base.html``. Some more HTML is
   rendered.
 * ``base.html`` executes ``self.body()``. The ``body()``
   body of the template, therefore the main body of
   ``index.html`` is rendered.
 * When ``<%block name="header">`` is encountered in ``index.html`` 
-  during the ``self.body()`` call, a conditional is checked - does the 
-  current inherited template, i.e. ``base.html``, also define this block ?  If yes,
-  the ``<%block>`` is **not** executed here - the inheritance 
+  during the ``self.body()`` call, a conditional is checked -- does the
+  current inherited template, i.e. ``base.html``, also define this block? If yes,
+  the ``<%block>`` is **not** executed here -- the inheritance
   mechanism knows that the parent template is responsible for rendering
   this block (and in fact it already has).  In other words a block
   only renders in its *basemost scope*.
 * Control comes back to ``base.html``. More HTML is rendered,
   then the ``<%block name="footer">`` expression is invoked.
 * The ``footer`` block is only defined in ``base.html``, so being
-  the topmost definition of ``footer``, its the one that
+  the topmost definition of ``footer``, it's the one that
   executes. If ``index.html`` also specified ``footer``, then
   its version would **override** that of the base.
 * ``base.html`` finishes up rendering its HTML and the template
   is complete, producing:
 
-.. sourcecode:: html
+  .. sourcecode:: html
 
         <html>
             <body>
                 <div class="header">
                     this is some header content
                 </div>
- 
+
                 this is the body content.
- 
+
                 <div class="footer">
                     this is the footer
                 </div>
 ==============
 
 The named blocks defined in an inherited template can also be nested within
-other blocks.   The name given to each block is globally accessible via any inheriting
-template.   We can add a new block ``title`` to our ``header`` block:
+other blocks.  The name given to each block is globally accessible via any inheriting
+template.  We can add a new block ``title`` to our ``header`` block:
 
 .. sourcecode:: mako
 
                     </h2>
                 </%block>
             </div>
- 
+
             ${self.body()}
- 
+
             <div class="footer">
                 <%block name="footer">
                     this is the footer
 
     ## index.html
     <%inherit file="base.html"/>
- 
+
     <%block name="header">
         this is some header content
         ${parent.header()}
     <%block name="title">
         this is the title
     </%block>
- 
+
     this is the body content.
 
 Note when we overrode ``header``, we added an extra call ``${parent.header()}`` in order to invoke
 ======================================
 
 Recall from the section :ref:`blocks` that a named block is just like a ``<%def>``,
-with some different usage rules.   We can call one of our named sections distinctly, for example
+with some different usage rules.  We can call one of our named sections distinctly, for example
 a section that is used more than once, such as the title of a page:
 
 .. sourcecode:: mako
 Where above an inheriting template can define ``<%block name="title">`` just once, and it will be
 used in the base template both in the ``<title>`` section as well as the ``<h2>``.
 
-But what about defs ?
+But what about defs?
 =====================
 
 The previous example used the ``<%block>`` tag to produce areas of content
-to be overridden.   Before Mako 0.4.1, there wasn't any such tag - instead
+to be overridden.  Before Mako 0.4.1, there wasn't any such tag -- instead
 there was only the ``<%def>`` tag.   As it turns out, named blocks and defs are
 largely interchangeable.  The def simply doesn't call itself automatically,
 and has more open-ended naming and scoping rules that are more flexible and similar
-to Python itself, but less suited towards layout.  The first example from 
+to Python itself, but less suited towards layout.  The first example from
 this chapter using defs would look like:
 
 .. sourcecode:: mako
 
     ## index.html
     <%inherit file="base.html"/>
- 
+
     <%def name="header()">
         this is some header content
     </%def>
- 
+
     this is the body content.
- 
+
 And ``base.html``, the inherited template:
 
 .. sourcecode:: mako
             <div class="header">
                 ${self.header()}
             </div>
- 
+
             ${self.body()}
- 
+
             <div class="footer">
                 ${self.footer()}
             </div>
         this is the footer
     </%def>
 
-Above, we illustrate that defs differ from blocks in that their definition 
-and invocation are defined in two separate places, instead of at once. You can *almost* do exactly what a 
+Above, we illustrate that defs differ from blocks in that their definition
+and invocation are defined in two separate places, instead of at once. You can *almost* do exactly what a
 block does if you put the two together:
 
 .. sourcecode:: mako
         the header
     </%block>
 
-So while the ``<%block>`` tag lifts the restriction of nested blocks not being available externally, 
+So while the ``<%block>`` tag lifts the restriction of nested blocks not being available externally,
 in order to achieve this it *adds* the restriction that all block names in a single template need
-to be globally unique within the template, and additionally that a ``<%block>`` can't be defined 
-inside of a ``<%def>``. It's a more restricted tag suited towards a more specific use case than ``<%def>``. 
+to be globally unique within the template, and additionally that a ``<%block>`` can't be defined
+inside of a ``<%def>``. It's a more restricted tag suited towards a more specific use case than ``<%def>``.
 
-Using the "next" namespace to produce content wrapping 
+Using the "next" namespace to produce content wrapping
 =======================================================
 
 Sometimes you have an inheritance chain that spans more than two
-templates. Or maybe you don't, but youd like to build your
+templates. Or maybe you don't, but you'd like to build your
 system such that extra inherited templates can be inserted in
 the middle of a chain where they would be smoothly integrated.
 If each template wants to define its layout just within its main
             <div class="header">
                 <%block name="header"/>
             </div>
- 
+
             ${next.body()}
- 
+
             <div class="footer">
                 <%block name="footer">
                     this is the footer
             <li>selection 1</li>
             <li>selection 2</li>
             <li>selection 3</li>
-        </%block> 
+        </%block>
     </ul>
     <div class="mainlayout">
         ${next.body()}
     </div>
- 
+
 
 And finally change ``index.html`` to inherit from
 ``layout.html`` instead:
 
     ## index.html
     <%inherit file="layout.html"/>
- 
+
     ## .. rest of template
- 
+
 In this setup, each call to ``next.body()`` will render the body
 of the next template in the inheritance chain (which can be
 written as ``base.html -> layout.html -> index.html``). Control
                 <li>selection 2</li>
                 <li>selection 3</li>
             </ul>
- 
+
             <div class="mainlayout">
             this is the body content.
             </div>
- 
+
             <div class="footer">
                 this is the footer
             </div>
 
 .. _parent_namespace:
 
-Using the "parent" namespace to augment defs 
+Using the "parent" namespace to augment defs
 =============================================
 
 Lets now look at the other inheritance-specific namespace, the
         <li>selection 4</li>
         <li>selection 5</li>
     </%block>
- 
+
     this is the body content.
 
 Above, we implemented a ``toolbar()`` function, which is meant
                 <li>selection 4</li>
                 <li>selection 5</li>
             </ul>
- 
+
             <div class="mainlayout">
             this is the body content.
             </div>
- 
+
             <div class="footer">
                 this is the footer
             </div>
         </body>
     </html>
 
-and you're now a template inheritance ninja !
+and you're now a template inheritance ninja!
 
 Inheritable Attributes
 ======================
     <%!
         class_ = "grey"
     %>
- 
+
     <div class="${self.attr.class_}">
         ${self.body()}
     </div>
- 
-If a an inheriting template overrides ``class_`` to be
+
+If an inheriting template overrides ``class_`` to be
 ``white``, as in:
 
 .. sourcecode:: mako
         class_ = "white"
     %>
     <%inherit file="parent.html"/>
- 
+
     This is the body
- 
-You'll get output like:
+
+you'll get output like:
 
 .. sourcecode:: html
 

doc/build/namespaces.rst

     <%def name="comp1()">
         this is comp1
     </%def>
- 
+
     <%def name="comp2(x)">
         this is comp2, x is ${x}
     </%def>
- 
-You can make another file, for example ``index.html``, that
+
+you can make another file, for example ``index.html``, that
 pulls those two defs into a namespace called ``comp``:
 
 .. sourcecode:: mako
 
     ## index.html
     <%namespace name="comp" file="components.html"/>
- 
-    Heres comp1:  ${comp.comp1()}
-    Heres comp2:  ${comp.comp2(x=5)}
+
+    Here's comp1:  ${comp.comp1()}
+    Here's comp2:  ${comp.comp2(x=5)}
 
 The ``comp`` variable above is an instance of
 :class:`.Namespace`, a **proxy object** which delivers
 .. sourcecode:: mako
 
     <%namespace file="components.html" import="comp1, comp2"/>
- 
+
     Heres comp1:  ${comp1()}
     Heres comp2:  ${comp2(x=5)}
- 
+
 ``import`` also supports the "*" operator:
 
 .. sourcecode:: mako
 The names imported by the ``import`` attribute take precedence
 over any names that exist within the current context.
 
-.. note:: in current versions of Mako, usage of ``import='*'`` is
+.. note:: In current versions of Mako, usage of ``import='*'`` is
    known to decrease performance of the template. This will be
    fixed in a future release.
 
-The ``file`` argument allows expressions - if looking for
+The ``file`` argument allows expressions -- if looking for
 context variables, the ``context`` must be named explicitly:
 
 .. sourcecode:: mako
 
     <%namespace name="dyn" file="${context['namespace_name']}"/>
- 
+
 Ways to Call Namespaces
 ========================
 
 .. sourcecode:: mako
 
     ${mynamespace.somefunction('some arg1', 'some arg2', arg3='some arg3', arg4='some arg4')}
- 
+
 Synonymous with the "expression" format is the "custom tag"
 format, when a "closed" tag is used. This format, introduced in
 Mako 0.2.3, allows the usage of a "custom" Mako tag, with the
 .. sourcecode:: mako
 
     <%mynamespace:somefunction arg1="some arg1" arg2="some arg2" arg3="some arg3" arg4="some arg4"/>
- 
+
 When using tags, the values of the arguments are taken as
 literal strings by default. To embed Python expressions as
 arguments, use the embedded expression format:
 
 .. _namespaces_python_modules:
 
-Namespaces from Regular Python Modules 
+Namespaces from Regular Python Modules
 ========================================
 
 Namespaces can also import regular Python functions from
         return ''
 
 A template can use this module via:
- 
+
 .. sourcecode:: mako
 
     <%namespace name="hw" module="some.module"/>
 
     ${hw.my_tag()}
- 
+
 Note that the ``context`` argument is not needed in the call;
 the :class:`.Namespace` tag creates a locally-scoped callable which
 takes care of it. The ``return ''`` is so that the def does not
-dump a ``None`` into the output stream - the return value of any
+dump a ``None`` into the output stream -- the return value of any
 def is rendered after the def completes, in addition to whatever
 was passed to :meth:`.Context.write` within its body.
 
 .. sourcecode:: python
 
     from mako.runtime import supports_caller
- 
+
     @supports_caller
     def my_tag(context):
         context.write("<div>")
         context['caller'].body()
         context.write("</div>")
         return ''
- 
+
 Capturing of output is available as well, using the
 outside-of-templates version of the :func:`.capture` function,
 which accepts the "context" as its first argument:
 Declaring defs in namespaces
 =============================
 
-The ``<%namespace>`` tag supports the definition of ``<%defs>``
+The ``<%namespace>`` tag supports the definition of ``<%def>``\ s
 directly inside the tag. These defs become part of the namespace
 like any other function, and will override the definitions
 pulled in from a remote template or module:
- 
+
 .. sourcecode:: mako
 
     ## define a namespace
             comp1
         </%def>
     </%namespace>
- 
+
     ## then call it
     ${stuff.comp1()}
 
 .. _namespaces_body:
 
-The "body()" method 
+The "body()" method
 =====================
 
 Every namespace that is generated from a template contains a
 
 Since the ``body()`` method is available from a namespace just
 like all the other defs defined in a template, what happens if
-you send arguments to it ? By default, the ``body()`` method
+you send arguments to it? By default, the ``body()`` method
 accepts no positional arguments, and for usefulness in
 inheritance scenarios will by default dump all keyword arguments
 into a dictionary called ``pageargs``. But if you actually want
 .. sourcecode:: mako
 
     <%page args="x, y, someval=8, scope='foo', **kwargs"/>
- 
+
 A template which defines the above signature requires that the
 variables ``x`` and ``y`` are defined, defines default values
 for ``someval`` and ``scope``, and sets up ``**kwargs`` to
 .. sourcecode:: mako
 
     ${self.body(5, y=10, someval=15, delta=7)}
- 
+
 The :class:`.Context` object also supplies a :attr:`~.Context.kwargs` accessor, for
-cases when youd like to pass along whatever is in the context to
+cases when you'd like to pass along whatever is in the context to
 a ``body()`` callable:
 
 .. sourcecode:: mako
 
 .. _namespaces_builtin:
 
-Built-in Namespaces 
+Built-in Namespaces
 ====================
 
 The namespace is so great that Mako gives your template one (or
 -----
 
 The ``self`` namespace, in the case of a template that does not
-use inheritance, is synonomous with ``local``. If inheritance is
+use inheritance, is synonymous with ``local``. If inheritance is
 used, then ``self`` references the topmost template in the
 inheritance chain, where it is most useful for providing the
 ultimate form of various "method" calls which may have been
 available throughout an inheritance chain (described in the next
 section), all the templates in an inheritance chain can get at
 the namespace imported in a super-template via ``self``.
- 
+
 .. sourcecode:: mako
 
     ## base.html
     <%namespace name="foo" file="foo.html" inheritable="True"/>
- 
+
     ${next.body()}
 
     ## somefile.html
     <%inherit file="base.html"/>
- 
+
     ${self.foo.bar()}
 
 This allows a super-template to load a whole bunch of namespaces

doc/build/runtime.rst

 .. _runtime_toplevel:
 
 =============================
-The Mako Runtime Environment 
+The Mako Runtime Environment
 =============================
 
 This section describes a little bit about the objects and
 ----------
 
 The buffer is stored within the :class:`.Context`, and writing
-to it is achieved by calling the :meth:`~.Context.write` method -
-in a template this looks like ``context.write('some string')``.
+to it is achieved by calling the :meth:`~.Context.write` method
+-- in a template this looks like ``context.write('some string')``.
 You usually don't need to care about this, as all text within a template, as
 well as all expressions provided by ``${}``, automatically send
 everything to this method. The cases you might want to be aware
 :class:`.Context`.
 
 * **What happens if I reference a variable name that is not in
-  the current context?** - the value you get back is a special
+  the current context?** - The value you get back is a special
   value called ``UNDEFINED``, or if the ``strict_undefined=True`` flag
   is used a ``NameError`` is raised. ``UNDEFINED`` is just a simple global
   variable with the class ``mako.runtime.Undefined``. The
   ``UNDEFINED`` object throws an error when you call ``str()`` on
   it, which is what happens if you try to use it in an
   expression.
-* **UNDEFINED makes it hard for me to find what name is missing** - An alternative 
+* **UNDEFINED makes it hard for me to find what name is missing** - An alternative
   introduced in version 0.3.6 is to specify the option
   ``strict_undefined=True``
-  to the :class:`.Template` or :class:`.TemplateLookup`.   This will cause
+  to the :class:`.Template` or :class:`.TemplateLookup`.  This will cause
   any non-present variables to raise an immediate ``NameError``
   which includes the name of the variable in its message
-  when :meth:`~.Template.render` is called - ``UNDEFINED`` is not used.
-* **Why not just return None?** Using ``UNDEFINED``, or 
+  when :meth:`~.Template.render` is called -- ``UNDEFINED`` is not used.
+* **Why not just return None?** Using ``UNDEFINED``, or
   raising a ``NameError`` is more
   explicit and allows differentiation between a value of ``None``
   that was explicitly passed to the :class:`.Context` and a value that
 * **Why raise an exception when you call str() on it ? Why not
   just return a blank string?** - Mako tries to stick to the
   Python philosophy of "explicit is better than implicit". In
-  this case, its decided that the template author should be made
+  this case, it's decided that the template author should be made
   to specifically handle a missing value rather than
   experiencing what may be a silent failure. Since ``UNDEFINED``
   is a singleton object just like Python's ``True`` or ``False``,
   you can use the ``is`` operator to check for it:
 
- .. sourcecode:: mako
- 
+  .. sourcecode:: mako
+
         % if someval is UNDEFINED:
             someval is: no value
         % else:
             someval is: ${someval}
         % endif
- 
+
 Another facet of the :class:`.Context` is that its dictionary of
 variables is **immutable**. Whatever is set when
 :meth:`~.Template.render` is called is what stays. Of course, since
           attributes['foo'] = 'bar'
       %>
       'foo' attribute is: ${attributes['foo']}
- 
+
 * **Why can't "attributes" be a built-in feature of the
   Context?** - This is an area where Mako is trying to make as
   few decisions about your application as it possibly can.
 * ``context[key]`` / ``context.get(key, default=None)`` -
   dictionary-like accessors for the context. Normally, any
   variable you use in your template is automatically pulled from
-  the context if it isnt defined somewhere already. Use the
+  the context if it isn't defined somewhere already. Use the
   dictionary accessor and/or ``get`` method when you want a
   variable that *is* already defined somewhere else, such as in
   the local arguments sent to a %def call. If a key is not
   propagate the variables in the current context to a function
   as keyword arguments, i.e.:
 
-.. sourcecode:: mako
+  .. sourcecode:: mako
 
         ${next.body(**context.kwargs)}
 
 ================
 
 Within ``% for`` blocks, the :ref:`reserved name<reserved_names>` ``loop``
-is available.  A new feature of Mako 0.7, ``loop`` tracks the progress of
+is available.  As a new feature of Mako 0.7, ``loop`` tracks the progress of
 the ``for`` loop and makes it easy to use the iteration state to control
 template behavior:
 
         % endfor
         </ul>
 
-With ``loop``, you get the same results with cleaner code and less prep work:
+With ``loop.cycle``, you get the same results with cleaner code and less prep work:
 
 .. sourcecode:: mako
 
         <table>
         % for consonant in 'pbj':
           <tr>
-         % for vowel in 'iou':
-           <td class="${'black' if (loop.parent.even == loop.even) else 'red'}">
-             ${consonant + vowel}t
-           </td>
-         % endfor 
+          % for vowel in 'iou':
+            <td class="${'black' if (loop.parent.even == loop.even) else 'red'}">
+              ${consonant + vowel}t
+            </td>
+          % endfor
           </tr>
-        % endfor 
+        % endfor
         </table>
 
 .. sourcecode:: html
           </tr>
         </table>
 
-
 .. _migrating_loop:
 
 Migrating Legacy Templates that Use the Word "loop"
 ---------------------------------------------------
 
 The ``loop`` name is now :ref:`reserved <reserved_names>` in Mako, which means a template that refers to a
-variable named ``loop`` won't function correctly when used in Mako 0.7.  To ease 
+variable named ``loop`` won't function correctly when used in Mako 0.7.  To ease
 the transition for such systems, the feature can be disabled across the board for
 all templates, then re-enabled on a per-template basis for those templates which wish
 to make use of the new system.
 
 Using the above scheme, it's safe to pass the name ``loop`` to the :meth:`.Template.render`
 method as well as to freely make usage of a variable named ``loop`` within a template, provided
-the ``<%page>`` tag doesn't override it.   New templates that want to use the ``loop`` context
+the ``<%page>`` tag doesn't override it.  New templates that want to use the ``loop`` context
 can then set up ``<%page enable_loop="True"/>`` to use the new feature without affecting
 old templates.
 
 these names other than ``context``, ``UNDEFINED``, and ``loop`` are
 also present *within* the :class:`.Context` itself.   The names
 ``context``, ``loop`` and ``UNDEFINED`` themselves can't be passed
-to the context and can't be substituted  - see the section :ref:`reserved_names`.
+to the context and can't be substituted -- see the section :ref:`reserved_names`.
 
 * ``context`` - this is the :class:`.Context` object, introduced
   at :ref:`context`.
 * ``UNDEFINED`` - a global singleton that is applied to all
   otherwise uninitialized template variables that were not
   located within the :class:`.Context` when rendering began,
-  unless the :class:`.Template` flag ``strict_undefined`` 
+  unless the :class:`.Template` flag ``strict_undefined``
   is set to ``True``. ``UNDEFINED`` is
   an instance of :class:`.Undefined`, and raises an
   exception when its ``__str__()`` method is called.
 --------------
 
 Mako has a few names that are considered to be "reserved" and can't be used
-as variable names.   As of 0.7, Mako raises an error if these words are found
+as variable names.  As of 0.7, Mako raises an error if these words are found
 passed to the template as context arguments, whereas in previous versions they'd be silently
-ignored or lead to other error messages.  
+ignored or lead to other error messages.
 
-* ``context`` - see :ref:`context`
-* ``UNDEFINED`` - see :ref:`context_vars`
+* ``context`` - see :ref:`context`.
+* ``UNDEFINED`` - see :ref:`context_vars`.
 * ``loop`` - see :ref:`loop_context`.  Note this can be disabled for legacy templates
   via the ``enable_loop=False`` argument; see :ref:`migrating_loop`.
 
 
 .. autoclass:: mako.runtime.Undefined
     :show-inheritance:
- 
 
-

doc/build/syntax.rst

 
 Above, the string representation of ``x`` is applied to the
 template's output stream. If you're wondering where ``x`` comes
-from, its usually from the ``Context`` supplied to the
+from, it's usually from the ``Context`` supplied to the
 template's rendering function. If ``x`` was not supplied to the
 template and was not otherwise assigned locally, it evaluates to
 a special value ``UNDEFINED``. More on that later.
- 
+
 The contents within the ``${}`` tag are evaluated by Python
 directly, so full expressions are OK:
 
 .. sourcecode:: mako
 
     pythagorean theorem:  ${pow(x,2) + pow(y,2)}
- 
+
 The results of the expression are evaluated into a string result
 in all cases before being rendered to the output stream, such as
 the above example where the expression produces a numeric
 Mako includes a number of built-in escaping mechanisms,
 including HTML, URI and XML escaping, as well as a "trim"
 function. These escapes can be added to an expression
-substituion using the ``|`` operator:
+substitution using the ``|`` operator:
 
 .. sourcecode:: mako
 
 escaping, whereas ``h`` represents HTML escaping, ``x``
 represents XML escaping, and ``trim`` applies a trim function.
 
-Read more about built in filtering functions, including how to
+Read more about built-in filtering functions, including how to
 make your own filter functions, in :ref:`filtering_toplevel`.
 
 Control Structures
 ==================
 
 A control structure refers to all those things that control the
-flow of a program - conditionals (i.e. if/else), loops (like
+flow of a program -- conditionals (i.e. if/else), loops (like
 while and for), as well as things like ``try/except``. In Mako,
 control structures are written using the ``%`` marker followed
 by a regular Python control expression, and are "closed" by
     % if x==5:
         this is some output
     % endif
- 
+
 The ``%`` can appear anywhere on the line as long as no text
-precedes it; indentation is not signficant. The full range of
+precedes it; indentation is not significant. The full range of
 Python "colon" expressions are allowed here, including
 ``if/elif/else``, ``while``, ``for``, and even ``def``, although
 Mako has a built-in tag for defs which is more full-featured.
 
     % for a in ['one', 'two', 'three', 'four', 'five']:
         % if a[0] == 't':
-         its two or three
+        its two or three
         % elif a[0] == 'f':
         four/five
         % else:
         one
-        %endif
+        % endif
     % endfor
 
 The ``%`` sign can also be "escaped", if you actually want to
 .. sourcecode:: mako
 
     %% some text
- 
+
         %% some more text
 
 The Loop Context
 ----------------
 
-Mako 0.7 includes a new feature called the **loop context** which 
+Mako 0.7 includes a new feature called the **loop context** which
 provides additional information about a loop while inside of a ``% for``
 structure:
 
     ## this is a comment.
     ...text ...
 
-A multiline version exists using ``<%doc>  ...text... </%doc>``:
+A multiline version exists using ``<%doc> ...text... </%doc>``:
 
 .. sourcecode:: mako
 
 
     here is a line that goes onto \
     another line.
- 
+
 The above text evaluates to::
 
     here is a line that goes onto another line.
- 
+
 Python Blocks
 =============
 
     % for elem in y:
         element: ${elem}
     % endfor
- 
+
 Within ``<% %>``, you're writing a regular block of Python code.
 While the code can appear with an arbitrary level of preceding
 whitespace, it has to be consistently formatted with itself.
     <%!
         import mylib
         import re
- 
+
         def filter(text):
             return re.sub(r'^@', '', text)
     %>
- 
+
 Any number of ``<%! %>`` blocks can be declared anywhere in a
 template; they will be rendered in the resulting module 
 in a single contiguous block above all render callables,
 .. sourcecode:: mako
 
     <%include file="foo.txt"/>
- 
+
     <%def name="foo" buffered="True">
         this is a def
     </%def>
- 
+
 All tags have a set of attributes which are defined for each
 tag. Some of these attributes are required. Also, many
 attributes support **evaluation**, meaning you can embed an
 .. sourcecode:: mako
 
     <%include file="/foo/bar/${myfile}.txt"/>
- 
+
 Whether or not an attribute accepts runtime evaluation depends
 on the type of tag and how that tag is compiled into the
 template. The best way to find out if you can stick an
-expression in is to try it ! The lexer will tell you if its not
+expression in is to try it! The lexer will tell you if it's not
 valid.
 
 Heres a quick summary of all the tags:
 .. sourcecode:: mako
 
     <%page args="x, y, z='default'"/>
- 
+
 Or a page tag that defines caching characteristics:
- 
+
 .. sourcecode:: mako
 
     <%page cached="True" cache_type="memory"/>
 defined in your template, else you may not get the results you
 want. The details of what ``<%page>`` is used for are described
 further in :ref:`namespaces_body` as well as :ref:`caching_toplevel`.
- 
+
 <%include>
 -----------
 
 .. sourcecode:: mako
 
     <%include file="header.html"/>
- 
+
         hello world
- 
+
     <%include file="footer.html"/>
 
 Include also accepts arguments which are available as ``<%page>`` arguments in the receiving template:
     <%def name="myfunc(x)">
         this is myfunc, x is ${x}
     </%def>
- 
+
     ${myfunc(7)}
- 
+
 The %def tag is a lot more powerful than a plain Python def, as
 the Mako compiler provides many extra services with %def that
 you wouldn't normally have, such as the ability to export defs
 <%block>
 ---------
 
-``%block`` is a tag that's new as of Mako 0.4.1.   It's close to 
+``%block`` is a tag that's new as of Mako 0.4.1. It's close to
 a ``%def``, except executes itself immediately in its base-most scope,
 and can also be anonymous (i.e. with no name):
 
         some <html> stuff.
     </%block>
 
-Inspired by Jinja2 blocks, named blocks offer a syntactically pleasing way 
+Inspired by Jinja2 blocks, named blocks offer a syntactically pleasing way
 to do inheritance:
 
 .. sourcecode:: mako
 When using the %inherit tag, control is passed to the topmost
 inherited template first, which then decides how to handle
 calling areas of content from its inheriting templates. Mako
-offers a lot of flexbility in this area, including dynamic
+offers a lot of flexibility in this area, including dynamic
 inheritance, content wrapping, and polymorphic method calls.
 Check it out in :ref:`inheritance_toplevel`.
 
 -------
 
 The call tag is the "classic" form of a user-defined tag, and is
-roughly equiavlent to the ``<%namespacename:defname>`` syntax
+roughly equivalent to the ``<%namespacename:defname>`` syntax
 described above. This tag is also described in :ref:`defs_with_content`.
 
 <%doc>
     <%text filter="h">
         heres some fake mako ${syntax}
         <%def name="x()">${x}</%def>
-    %CLOSETEXT
+    <%/text>
 
 Returning early from a template
 ===============================
 
 Sometimes you want to stop processing a template or ``<%def>``
 method in the middle and just use the text you've accumulated so
-far. You can use a ````return```` statement inside a Python
+far. You can use a ``return`` statement inside a Python
 block to do that.
 
 .. sourcecode:: mako

doc/build/unicode.rst

 before the Unicode standard was even available, back when
 strings were C-style strings and were just that, a series of
 bytes. Strings that had only values below 128 just happened to
-be **ascii** strings and were printable on the console, whereas
+be **ASCII** strings and were printable on the console, whereas
 strings with values above 128 would produce all kinds of
 graphical characters and bells.
 
-Contrast the "bytestring" types with the "unicode/string" type.
-Objects of this type are created whenever you say something like
+Contrast the "byte-string" type with the "unicode/string" type.
+Objects of this latter type are created whenever you say something like
 ``u"hello world"`` (or in Python 3, just ``"hello world"``). In this
 case, Python represents each character in the string internally
 using multiple bytes per character (something similar to
-UTF-16). Whats important is that when using the
+UTF-16). What's important is that when using the
 ``unicode``/``string`` type to store strings, Python knows the
-data's encoding; its in its own internal format. Whereas when
+data's encoding; it's in its own internal format. Whereas when
 using the ``string``/``bytes`` type, it does not.
 
 When Python 2 attempts to treat a byte-string as a string, which
-means its attempting to compare/parse its characters, to coerce
+means it's attempting to compare/parse its characters, to coerce
 it into another encoding, or to decode it to a unicode object,
 it has to guess what the encoding is. In this case, it will
-pretty much always guess the encoding as ``ascii``...and if the
-bytestring contains bytes above value 128, you'll get an error.
+pretty much always guess the encoding as ``ascii``... and if the
+byte-string contains bytes above value 128, you'll get an error.
 Python 3 eliminates much of this confusion by just raising an
-error unconditionally if a bytestring is used in a
+error unconditionally if a byte-string is used in a
 character-aware context.
 
-There is one operation that Python *can* do with a non-ascii
-bytestring, and its a great source of confusion: it can dump the
-bytestring straight out to a stream or a file, with nary a care
+There is one operation that Python *can* do with a non-ASCII
+byte-string, and it's a great source of confusion: it can dump the
+byte-string straight out to a stream or a file, with nary a care
 what the encoding is. To Python, this is pretty much like
 dumping any other kind of binary data (like an image) to a
 stream somewhere. In Python 2, it is common to see programs that
 embed all kinds of international characters and encodings into
 plain byte-strings (i.e. using ``"hello world"`` style literals)
 can fly right through their run, sending reams of strings out to
-whereever they are going, and the programmer, seeing the same
+wherever they are going, and the programmer, seeing the same
 output as was expressed in the input, is now under the illusion
 that his or her program is Unicode-compliant. In fact, their
 program has no unicode awareness whatsoever, and similarly has
 operation when using Python 2, using the "disable_unicode=True"
 flag. However, when using Mako in its default mode of
 unicode-aware, it requires explicitness when dealing with
-non-ascii encodings. Additionally, if you ever need to handle
+non-ASCII encodings. Additionally, if you ever need to handle
 unicode strings and other kinds of encoding conversions more
-intelligently, the usage of raw bytestrings quickly becomes a
+intelligently, the usage of raw byte-strings quickly becomes a
 nightmare, since you are sending the Python interpreter
 collections of bytes for which it can make no intelligent
 decisions with regards to encoding. In Python 3 Mako only allows
 
 In normal Mako operation, all parsed template constructs and
 output streams are handled internally as Python ``unicode``
-objects. Its only at the point of :meth:`~.Template.render` that this unicode
+objects. It's only at the point of :meth:`~.Template.render` that this unicode
 stream may be rendered into whatever the desired output encoding
 is. The implication here is that the template developer must
-ensure that the encoding of all non-ascii templates is explicit
-(still required in Python 3), that all non-ascii-encoded
+ensure that the encoding of all non-ASCII templates is explicit
+(still required in Python 3), that all non-ASCII-encoded
 expressions are in one way or another converted to unicode (not
 much of a burden in Python 3), and that the output stream of the
 template is handled as a unicode stream being encoded to some
 This is the most basic encoding-related setting, and it is
 equivalent to Python's "magic encoding comment", as described in
 `pep-0263 <http://www.python.org/dev/peps/pep-0263/>`_. Any
-template that contains non-ascii characters requires that this
+template that contains non-ASCII characters requires that this
 comment be present so that Mako can decode to unicode (and also
 make usage of Python's AST parsing services). Mako's lexer will
 use this encoding in order to convert the template source into a
      « S’il vous plaît… dessine-moi un mouton! »
 
 For the picky, the regular expression used is derived from that
-of the abovementioned pep:
- 
+of the above mentioned pep:
+
 .. sourcecode:: python
 
     #.*coding[:=]\s*([-\w.]+).*\n
 .. sourcecode:: python
 
     t = TemplateLookup(directories=['./'], input_encoding='utf-8')
- 
+
 The above will assume all located templates specify ``utf-8``
 encoding, unless the template itself contains its own magic
 encoding comment, which takes precedence.
 .. sourcecode:: mako
 
     ${"hello world"}
- 
+
 looks something like this:
 
 .. sourcecode:: python
 
     context.write(unicode("hello world"))
 
-In Python 3, its just:
+In Python 3, it's just:
 
 .. sourcecode:: python
 
     context.write(str("hello world"))
- 
+
 That is, **the output of all expressions is run through the
-``unicode`` builtin**. This is the default setting, and can be
+``unicode`` built-in**. This is the default setting, and can be
 modified to expect various encodings. The ``unicode`` step serves
 both the purpose of rendering non-string expressions into
 strings (such as integers or objects which contain ``__str()__``
 methods), and to ensure that the final output stream is
 constructed as a unicode object. The main implication of this is
-that **any raw bytestrings that contain an encoding other than
-ascii must first be decoded to a Python unicode object**. It
+that **any raw byte-strings that contain an encoding other than
+ASCII must first be decoded to a Python unicode object**. It
 means you can't say this in Python 2:
 
 .. sourcecode:: mako
 
 Similarly, if you are reading data from a file that is streaming
 bytes, or returning data from some object that is returning a
-Python bytestring containing a non-ascii encoding, you have to
-explcitly decode to unicode first, such as:
+Python byte-string containing a non-ASCII encoding, you have to
+explicitly decode to unicode first, such as:
 
 .. sourcecode:: mako
 
     ${call_my_object().decode('utf-8')}
- 
+
 Note that filehandles acquired by ``open()`` in Python 3 default
 to returning "text", that is the decoding is done for you. See
-Python 3's documentation for the ``open()`` builtin for details on
+Python 3's documentation for the ``open()`` built-in for details on
 this.
 
 If you want a certain encoding applied to *all* expressions,
-override the ``unicode`` builtin with the ``decode`` builtin at the
+override the ``unicode`` builtin with the ``decode`` built-in at the
 :class:`.Template` or :class:`.TemplateLookup` level:
 
 .. sourcecode:: python
     t = Template(templatetext, default_filters=['decode.utf8'])
 
 Note that the built-in ``decode`` object is slower than the
-``unicode`` function, since unlike ``unicode`` its not a Python
-builtin, and it also checks the type of the incoming data to
+``unicode`` function, since unlike ``unicode`` it's not a Python
+built-in, and it also checks the type of the incoming data to
 determine if string conversion is needed first.
 
 The ``default_filters`` argument can be used to entirely customize
 the filtering process of expressions. This argument is described
 in :ref:`filtering_default_filters`.
- 
+
 Defining Output Encoding
 =========================
 
 
     from mako.template import Template
     from mako.lookup import TemplateLookup
- 
+
     mylookup = TemplateLookup(directories=['/docs'], output_encoding='utf-8', encoding_errors='replace')
- 
+
     mytemplate = mylookup.get_template("foo.txt")
     print mytemplate.render()
 
 .. sourcecode:: python
 
     print mytemplate.render_unicode()
- 
+
 The above method disgards the output encoding keyword argument;
 you can encode yourself by saying:
 
 .. sourcecode:: python
 
     print mytemplate.render_unicode().encode('utf-8', 'replace')
- 
+
 Buffer Selection
 -----------------
 
 Mako does play some games with the style of buffering used
 internally, to maximize performance. Since the buffer is by far
-the most heavily used object in a render operation, its
+the most heavily used object in a render operation, it's
 important!
 
 When calling :meth:`~.Template.render` on a template that does not specify any
-output encoding (i.e. its ``ascii``), Python's ``cStringIO`` module,
-which cannot handle encoding of non-ascii ``unicode`` objects
-(even though it can send raw bytestrings through), is used for
+output encoding (i.e. it's ``ascii``), Python's ``cStringIO`` module,
+which cannot handle encoding of non-ASCII ``unicode`` objects
+(even though it can send raw byte-strings through), is used for
 buffering. Otherwise, a custom Mako class called
 ``FastEncodingBuffer`` is used, which essentially is a super
 dumbed-down version of ``StringIO`` that gathers all strings into
 a list and uses ``u''.join(elements)`` to produce the final output
-- its markedly faster than ``StringIO``.
+-- it's markedly faster than ``StringIO``.
 
 .. _unicode_disabled:
 
 Saying to Heck with it: Disabling the usage of Unicode entirely
 ================================================================
 
-Some segements of Mako's userbase choose to make no usage of
-Unicode whatsoever, and instead would prefer the "passthru"
+Some segments of Mako's userbase choose to make no usage of
+Unicode whatsoever, and instead would prefer the "pass through"
 approach; all string expressions in their templates return
-encoded bytestrings, and they would like these strings to pass
+encoded byte-strings, and they would like these strings to pass
 right through. The only advantage to this approach is that
 templates need not use ``u""`` for literal strings; there's an
-arguable speed improvement as well since raw bytestrings
+arguable speed improvement as well since raw byte-strings