[svn] again some updates on the documentation for jinja. this time the debugging...

--HG--
branch : trunk

diff --git a/docs/src/debugging.txt b/docs/src/debugging.txt
new file mode 100644 (file)
index 0000000..a67f989
--- /dev/null
+++ b/docs/src/debugging.txt
@@ -0,0 +1,27 @@
+===================
+Debugging Templates
+===================
+
+In order to keep templates debuggable you have to do some additional work on
+the application side. The traceback module that comes with python currently
+does not support the `__loader__` hook which is used by Jinja to provide
+templates. Although the import system was implemented three Python versions
+ago the default traceback system still doesn't support it.
+
+However most of the extended web development traceback module support it:
+
+-  `Colubrid Debugging Middleware`_
+-  `cgitb`_
+-  `EvalException`_
+
+Note that the django traceback module currently does not provide this. `A
+ticket`_ was filed already so there is hope that this will be fixed.
+
+To enable debugging you have to use one of those debugging systems or
+implement your own one with support for `__loader__`.
+
+
+.. _Colubrid Debugging Middleware: http://trac.pocoo.org/repos/colubrid/trunk/colubrid/debug.py
+.. _cgitb: http://docs.python.org/lib/module-cgitb.html
+.. _EvalException: http://pythonpaste.org/module-paste.evalexception.html
+.. _A ticket: http://code.djangoproject.com/ticket/3734

diff --git a/docs/src/designerdoc.txt b/docs/src/designerdoc.txt
index 7f0c96cf1bbd3529ed67ea4c58bbcf5f17caf731..df3ca95eb2cbeb00176d33ea2622333689d0b4c9 100644 (file)
--- a/docs/src/designerdoc.txt
+++ b/docs/src/designerdoc.txt
@@ -283,6 +283,51 @@ Note that there is no support for any bit operations or something similar.
   instead of ``not foo is bar`` and ``not foo in bar``. All other expressions
   require a prefix notation: ``not (foo and bar)``.
 
+Boolean Values
+==============
+
+In If-Conditions Jinja performs a boolean check. All empty values (eg: empty
+lists ``[]``, empty dicts ``{}`` etc) evaluate to `false`. Numbers that are
+equal to `0`/`0.00` are considered `false` too. The boolean value of other
+objects depends on the behavior the application developer gave it. Usually
+items are `true`.
+
+Here some examples that should explain it:
+
+.. sourcecode:: jinja
+
+    {% if [] %}
+        will always be false because it's an empty list
+
+    {% if {} %}
+        false too.
+
+    {% if ['foo'] %}
+        this is true. Because the list is not empty.
+
+    {% if "foobar" %}
+        this is also true because the string is not empty.
+
+Slicing
+=======
+
+Some objects support slicing operations. For example lists:
+
+.. sourcecode:: jinja
+
+    {% for item in items[:5] %}
+        This will only iterate over the first 5 items of the list
+
+    {% for item in items[5:10] %}
+        This will only iterate from item 5 to 10.
+
+    {% for item in items[:10:2] %}
+        This will only yield items from start to ten and only returing
+        even items.
+
+For more informations about slicing have a look at the `slicing chapter`_
+in the "Dive into Python" e-book.
+
 Macros
 ======
 
@@ -592,3 +637,5 @@ in the ``trans`` header.
         {% else %}
             one user found.
         {% endif %}
+
+.. _slicing chapter: http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice

diff --git a/docs/src/index.txt b/docs/src/index.txt
index d4e539450ebecefd9755073288f0d80fe2023a0a..aa24641cd7faa833db3f5f1c5bc06cd2b690bad4 100644 (file)
--- a/docs/src/index.txt
+++ b/docs/src/index.txt
@@ -24,6 +24,8 @@ Welcome in the Jinja documentation.
 
   - `Framework Integration <frameworks.txt>`_
 
+  - `Debugging Support <debugging.txt>`_
+
 - Template Designer Documentation:
 
   - `Syntax Reference <designerdoc.txt>`_
@@ -44,7 +46,3 @@ Undocumented So Far
 - Jinja in TurboGears / django?
 
 - Changelog / Authors
-
-- Boolean Rules (empty lists evaluate to False etc)
-
-- Slicing