Improve readme

README.md

@@ -2,7 +2,8 @@ Stencil
 =======
 
 Stencil is a simple and powerful template language for Swift. It provides a
-syntax similar to Django and Jinja2.
+syntax similar to Django and Jinja2. If you're familiar with these, you will
+feel right at home with Stencil.
 
 ### Example
 
@@ -32,6 +33,105 @@ if let error = result.error {
 println("\(result.string)")
 ```
 
+## Philosophy
+
+Stencil follows the same philosophy of Django:
+
+> If you have a background in programming, or if you’re used to languages which
+> mix programming code directly into HTML, you’ll want to bear in mind that the
+> Django template system is not simply Python embedded into HTML. This is by
+> design: the template system is meant to express presentation, not program
+> logic.
+
+## Templates
+
+### Variables
+
+A variable can be defined in your template using the following:
+
+```html+django
+{{ variable }}
+```
+
+Stencil will look up the variable inside the current variable context and
+evaluate it. When a variable contains a dot, it will try doing the
+following lookup:
+
+- Context lookup
+- Dictionary lookup
+- Array lookup (first, last, count, index)
+- Key value coding lookup
+
+For example, if `people` was an array:
+
+```html+django
+There are {{ people.count }} people, {{ people.first }} is first person.
+Followed by {{ people.1 }}.
+```
+
+### Tags
+
+Tags are a mechanism to execute a piece of code which can allows you to have
+control flow within your template.
+
+```html+django
+{% if variable %}
+  {{ variable }} was found.
+{% endif %}
+```
+
+A tag can also effect the context and define variables as follows:
+
+```html+django
+{% for item in items %}
+  {{ item }}
+{% endfor %}
+```
+
+Stencil has a couple of built in tags which are listed below. You will also be
+able to use the Stencil API to build your own in future versions. This is
+tracked by a ticket [#6](https://github.com/kylef/Stencil/issues/6).
+
+#### for
+
+A for loop allows you to iterate over an array found by variable lookup.
+
+```html+django
+{% for item in items %}
+  {{ item }}
+{% empty %}
+  There we're no items.
+{% endfor %}
+```
+
+#### if
+
+```html+django
+{% if variable %}
+  The variable was found in the current context.
+{% else %}
+  The variable was not found.
+{% endif %}
+```
+
+#### ifnot
+
+```html+django
+{% ifnot variable %}
+  The variable was NOT found in the current context.
+{% else %}
+  The variable was found.
+{% endif %}
+```
+
+### Comments
+
+To comment out part of your template you can use the following syntax:
+
+```html+django
+{# My comment is completely hidden #}
+```
+
 ## License
 
 Stencil is licensed under the BSD license. See [LICENSE](LICENSE) for more