mention defs can return data / better buffering explanation

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:)

Search the Mako documentation for the existing sections explaining buffering and defs, then read the surrounding examples and documentation structure. Update those explanations to address the requested syntax and that defs can return values while rendering their body, and verify the examples against the documented behavior.