- reword the docs a bit
- PR is done, fixes #236
diff --git a/doc/build/changelog.rst b/doc/build/changelog.rst
index 9c321bb..e2717cf 100644
--- a/doc/build/changelog.rst
+++ b/doc/build/changelog.rst
@@ -12,11 +12,16 @@
:tags: feature
:tickets: 236
- Added STOP_RENDERING keyword for returning/exiting from a
- template early. Previously the docs suggested a bare
+ Added ``STOP_RENDERING`` keyword for returning/exiting from a
+ template early, which is a synonym for an empty string ``""``.
+ Previously, the docs suggested a bare
``return``, but this could cause ``None`` to appear in the
rendered template result.
+ .. seealso::
+
+ :ref:`syntax_exiting_early`
+
.. changelog::
:version: 1.0.1
:released: Thu Jan 22 2015
diff --git a/doc/build/syntax.rst b/doc/build/syntax.rst
index 7ec68cb..e3dd7db 100644
--- a/doc/build/syntax.rst
+++ b/doc/build/syntax.rst
@@ -212,7 +212,7 @@
%>
Any number of ``<%! %>`` blocks can be declared anywhere in a
-template; they will be rendered in the resulting module
+template; they will be rendered in the resulting module
in a single contiguous block above all render callables,
in the order in which they appear in the source template.
@@ -443,13 +443,19 @@
<%def name="x()">${x}</%def>
</%text>
+.. _syntax_exiting_early:
+
Exiting 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 ``return`` the ``STOP_RENDERING`` value inside a Python
-block to exit the current rendering process.
+far. This is accomplished by using ``return`` statement inside
+a Python block. It's a good idea for the ``return`` statement
+to return an empty string, which prevents the Python default return
+value of ``None`` from being rendered by the template. This
+return value is for semantic purposes provided in templates via
+the ``STOP_RENDERING`` symbol:
.. sourcecode:: mako
@@ -467,12 +473,14 @@
return STOP_RENDERING
%>
-In older versions, return an empty string instead to avoid having
-``None`` in your rendered template:
+In older versions of Mako, an empty string can be substituted for
+the ``STOP_RENDERING`` symbol:
.. sourcecode:: mako
<% return '' %>
-.. versionadded:: 1.0.2
+.. versionadded:: 1.0.2 - added the ``STOP_RENDERING`` symbol which serves
+ as a semantic identifier for the empty string ``""`` used by a
+ Python ``return`` statement.
