mention defs can return data / better buffering explanation

[sqlalchemy-bot]

Migrated issue, originally created by Anonymous

Today I (finally) got how "buffering" works.

I think documentation could do better at explaining how this things work behind mako scenes.

First of all, all ${ call_some_function() } should be changed to <% call_some_function() %> for sake of understanding.

Secondly, it would be wise to mention that defs can return values. Example:

<%def name="hello_world()">
    hello world
    <% return True %>
<%/dev>

<% 
   success = hello_world() ## also renders the body because of buffering
%> 

that's my two cents:)