added documentation for all extensions

README

@@ -4,11 +4,4 @@ Twig Extensions Repository
 This repository hosts Twig Extensions that do not belong to the core but can
 be nonetheless interesting to share with other developers.
 
-This extension adds the following filters
-
-* truncate
-* wordwrap
-* n12br
-* sluggize
-
 Fork this repository, add your extension, and request a pull.

doc/debug.rst

@@ -0,0 +1,23 @@
+The Debug Extension
+===================
+
+The ``debug`` extension provides a ``debug`` tag that can be used to
+output the content of the current context:
+
+.. code-block:: jinja
+
+    {% debug %}
+
+This is really useful when a template does not work as expected. You can also
+output a specific variable or an expression:
+
+.. code-block:: jinja
+
+    {% debug items %}
+
+    {% debug post.body %}
+
+.. warning::
+
+    The ``debug`` tag only works when the ``debug`` environment option is set
+    to ``true``.

doc/i18n.rst

@@ -0,0 +1,154 @@
+The i18n Extension
+==================
+
+Configuration
+-------------
+
+The ``i18n`` extension adds `gettext`_ support to Twig. It defines one tag,
+``trans``.
+
+You need to register this extension before using the ``trans`` block::
+
+    $twig->addExtension(new Twig_Extensions_Extension_I18n());
+
+Note that you must configure the ``gettext`` extension before rendering any
+internationalized template. Here is a simple configuration example from the
+PHP `documentation`_::
+
+    // Set language to French
+    putenv('LC_ALL=fr_FR');
+    setlocale(LC_ALL, 'fr_FR');
+
+    // Specify the location of the translation tables
+    bindtextdomain('myAppPhp', 'includes/locale');
+    bind_textdomain_codeset('myAppPhp', 'UTF-8');
+
+    // Choose domain
+    textdomain('myAppPhp');
+
+.. caution::
+
+    The ``i18n`` extension only works if the PHP `gettext`_ extension is
+    enabled.
+
+Usage
+-----
+
+Use the ``trans`` block to mark parts in the template as translatable:
+
+.. code-block: jinja
+
+    {% trans "Hello World!" %}
+
+    {% trans string_var %}
+
+    {% trans %}
+        Hello World!
+    {% endtrans %}
+
+In a translatable string, you can embed variables:
+
+.. code-block: jinja
+
+    {% trans %}
+        Hello {{ name }}!
+    {% endtrans %}
+
+.. note::
+
+    ``{% trans "Hello {{ name }}!" %}`` is not a valid statement.
+
+If you need to apply filters to the variables, you first need to assign the
+result to a variable:
+
+.. code-block: jinja
+
+    {% set name = name|capitalize %}
+
+    {% trans %}
+        Hello {{ name }}!
+    {% endtrans %}
+
+To pluralize a translatable string, use the ``plural`` block:
+
+.. code-block: jinja
+
+    {% trans %}
+        Hey {{ name }}, I have one apple.
+    {% plural apple_count %}
+        Hey {{ name }}, I have {{ count }} apples.
+    {% endtrans %}
+
+The ``plural`` tag should provide the ``count`` used to select the right
+string. Within the translatable string, the special ``count`` variable always
+contain the count value (here the value of ``apple_count``).
+
+Within an expression or in a tag, you can use the ``trans`` filter to translate
+simple strings or variables:
+
+.. code-block: jinja
+
+    {{ var|default(default_value|trans) }}
+
+Complex Translations within an Expression or Tag
+------------------------------------------------
+
+Translations can be done with both the ``trans`` tag and the ``trans`` filter.
+The filter is less powerful as it only works for simple variables or strings.
+For more complex scenario, like pluralization, you can use a two-step
+strategy:
+
+.. code-block: jinja
+
+    {# assign the translation to a temporary variable #}
+    {% set default_value %}
+        {% trans %}
+          Hey {{ name }}, I have one apple.
+        {% plural apple_count %}
+          Hey {{ name }}, I have {{ count }} apples.
+        {% endtrans %}
+    {% endset %}
+
+    {# use the temporary variable within an expression #}
+    {{ var|default(default_value|trans) }}
+
+Extracting Template Strings
+---------------------------
+
+If you use the Twig I18n extension, you will probably need to extract the
+template strings at some point. Unfortunately, the ``xgettext`` utility does
+not understand Twig templates natively. But there is a simple workaround: as
+Twig converts templates to PHP files, you can use ``xgettext`` on the template
+cache instead.
+
+Create a script that forces the generation of the cache for all your
+templates. Here is a simple example to get you started::
+
+    $tplDir = dirname(__FILE__).'/templates';
+    $tmpDir = '/tmp/cache/';
+    $loader = new Twig_Loader_Filesystem($tplDir);
+
+    // force auto-reload to always have the latest version of the template
+    $twig = new Twig_Environment($loader, array(
+        'cache' => $tmpDir,
+        'auto_reload' => true
+    ));
+    $twig->addExtension(new Twig_Extensions_Extension_I18n());
+    // configure Twig the way you want
+
+    // iterate over all your templates
+    foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($tplDir), RecursiveIteratorIterator::LEAVES_ONLY) as $file)
+    {
+      // force compilation
+      $twig->loadTemplate(str_replace($tplDir.'/', '', $file));
+    }
+
+Use the standard ``xgettext`` utility as you would have done with plain PHP
+code:
+
+.. code-block: plain
+
+    xgettext --default-domain=messages -p ./locale --from-code=UTF-8 -n --omit-header -L PHP /tmp/cache/*.php
+
+.. _`gettext`:       http://www.php.net/gettext
+.. _`documentation`: http://fr.php.net/manual/en/function.gettext.php

doc/index.rst

@@ -0,0 +1,20 @@
+Twig Extensions
+===============
+
+.. toctree::
+    :hidden:
+
+    debug
+    text
+    i18n
+
+The Twig Extensions repository provides several useful extensions for Twig:
+
+* *:doc:`Twig_Extensions_Extension_Debug <debug>`*: Provides tags and filters
+  to ease template debugging;
+
+* *:doc:`Twig_Extensions_Extension_Text <text>`*: Provides useful filters for
+  text manipulation;
+
+* *:doc:`Twig_Extensions_Extension_I18n <i18n>`*: Adds internationalization
+  support via the ``gettext`` library.

doc/text.rst

@@ -0,0 +1,8 @@
+The Text Extension
+==================
+
+The Text extensions provides the following filters:
+
+* ``truncate``
+* ``wordwrap``
+* ``nl2br``