Updated documentation on SimpleTemplate and embedded blocks.

[vsajip]

As discussed in #1027.

[Jwink3101]

This is more than needed. All you need to say is that the same white space rules apply as inline. Indentation is ignored and blocks must be ended. It also comes off a bit editorialized

[vsajip]

This is more than needed.

I get this, but

It also comes off a bit editorialized

not sure what you mean by this.

[Jwink3101]

The not being valid python it is valid except for the end statement.

Also, on another note, simple template doesn’t evaluate the code. It just parses for the key words and then python evaluates that. It’s an important distinction because the engine isn’t reimplementing logic.

[vsajip]

The not being valid python it is valid except for the end statement.

Yes, I wrote

might need to be not actually valid Python as understood by the Python parser, but close to it.

which would seem to cover it. I don't mind changing close to very close.

I also didn't say that SimpleTemplate evaluated the code - I used the terms parsed, translated and generated, which seem appropriate in this context.

[defnull]

The examples are a little misleading I think. The indentation counter is not reset at the %> token. Not using end to close a python block is always wrong, even if the result might look right.

I prefer to reason about this in two steps: % and <%%> are used to mark single lines or multiple lines as code. All lines that are not code are translated into _printline(...) statements. Then the result is re-intended as if it were valid python code with an aditional required end keyword.

The key message is that % and <%%> work exactly the same way. The latter is only a convenient way to type less for longer code segments.

[vsajip]

I get this now. The thing that threw me was that every example in the current documentation has % end on single lines, and there are no examples of using end in a <% %> block. I naïvely tried % end inside the <% %>, which of course didn't work, and that led to me raising #1027. Following the discussion there, I knew what I had to do; I only wanted to update the documentation to make it clearer for anyone else who ran into this.

Would it be better to have an example with more levels of indentation, and mixing <% %> and % lines and showing the generated result? Or is that overkill, as @Jwink3101 seems to think? Or perhaps just a very short update along the lines of

% and <% %> work exactly the same way. The latter is only a convenient way to type less for longer code segments.

I think it would be good to have an example of a <% %> block which shows indented blocks and end.