Mention simple_tag and inclusion_tag before manual parsing

[Waldemar Kornewald]

The current docs begin with explaining the complicated parsing system. This really gives the wrong impression that you always have to create parser and go through all those hoops every time you need a tag or do some simple logic that isn't available in the templates. I'd like to suggest that the documentation talk about simple_tag and inclusion_tag before turning potential users away with those complicated examples. Well, you nearly turned me away.

[Waldemar Kornewald]

minor improvement; on the long run the whole docs should be restructured

[James Bennett]

The way this is handled is consistent with other documentation and tutorials; first the "full" method of doing something is shown, then any relevant shortcuts are explained (e.g., the tutorial first shows you how to manually load a template, instantiate a context, render the template and return a response, then introduces the render_to_response() shortcut). This is generally a useful pattern because it ensures newcomers see how something works before using an abstraction which hides the underlying details. In that sense, it's somewhat like teaching someone a multiplication table before letting them use a calculator.

[bocman1 <Bocman1@…>]

​http://www.dizmex.com

[Waldemar Kornewald]

The current situation looks more like you'd have to learn group theory before learning the multiplication table because that goes into deeper detail. Seriously, the documentation makes templates look very ugly and complicated although they don't have to be that way. At least, you could mention that there is a simpler alternative before going into the ugly details (which is what my patch does).