Updated documentation on SimpleTemplate and embedded blocks. (#1028)

* Updated documentation on SimpleTemplate and embedded blocks.
* Addressed review comments.

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/stpl.rst b/docs/stpl.rst
index 155b4b9..bee165f 100755
--- a/docs/stpl.rst
+++ b/docs/stpl.rst
@@ -95,6 +95,21 @@ Both the ``%`` and the ``<%`` tokens are only recognized if they are the first n
 
 If you find yourself needing to escape a lot, consider using :ref:`custom tokens <stpl-custom-tokens>`.
 
+Note that ``%`` and ``<% %>`` work in *exactly* the same way. The latter is only a convenient way to type less and avoid clutter for longer code segments. This means that in ``<% %>`` blocks, all indented code must be terminated with an ``end``, as in the following example::
+
+    <%
+        if some_condition:
+            some_operation()
+        elif some_other_condition:
+            some_other_operation()
+        else:
+            yet_another_operation()
+            if yet_another_condition:
+              some_more_stuff()
+            end
+        end
+    %>
+
 Whitespace Control
 -----------------------