feature #3877 Added a note about configuring several paths under the same namespace (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Added a note about configuring several paths under the same namespace

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | 2.3+
| Fixed tickets | #3661

Commits
-------

fb5388c Added a comma
40524ca Fixed the case of the headings
857c6cd Minor simplification of the XML code
29863f1 Added a note about configuring several paths under the same namespace

Author: weaverryan

Diff for: cookbook/templating/namespaced_paths.rst

@@ -1,7 +1,7 @@
 .. index::
    single: Templating; Namespaced Twig Paths
 
-How to use and Register namespaced Twig Paths
+How to Use and Register Namespaced Twig Paths
 =============================================
 
 .. versionadded:: 2.2
@@ -33,7 +33,7 @@ Both paths are valid and functional by default in Symfony2.
 
     As an added bonus, the namespaced syntax is faster.
 
-Registering your own namespaces
+Registering your own Namespaces
 -------------------------------
 
 You can also register your own custom namespaces. Suppose that you're using
@@ -81,3 +81,55 @@ called ``sidebar.twig`` in that directory, you can use it easily:
 .. code-block:: jinja
 
     {% include '@foo_bar/sidebar.twig' %}
+
+Multiple Paths per Namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also assign several paths to the same template namespace. The order in
+which paths are configured is very important, because Twig will always load
+the first template that exists, starting from the first configured path. This
+feature can be used as a fallback mechanism to load generic templates when the
+specific template doesn't exist.
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        twig:
+            # ...
+            paths:
+                "%kernel.root_dir%/../vendor/acme/themes/theme1": theme
+                "%kernel.root_dir%/../vendor/acme/themes/theme2": theme
+                "%kernel.root_dir%/../vendor/acme/themes/common": theme
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+                   xmlns:twig="http://symfony.com/schema/dic/twig"
+        >
+
+            <twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%">
+                <twig:path namespace="theme">%kernel.root_dir%/../vendor/acme/themes/theme1</twig:path>
+                <twig:path namespace="theme">%kernel.root_dir%/../vendor/acme/themes/theme2</twig:path>
+                <twig:path namespace="theme">%kernel.root_dir%/../vendor/acme/themes/common</twig:path>
+            </twig:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('twig', array(
+            'paths' => array(
+                '%kernel.root_dir%/../vendor/acme/themes/theme1' => 'theme',
+                '%kernel.root_dir%/../vendor/acme/themes/theme2' => 'theme',
+                '%kernel.root_dir%/../vendor/acme/themes/common' => 'theme',
+            );
+        ));
+
+Now, you can use the same ``@theme`` namespace to refer to any template located
+in the previous three directories:
+
+.. code-block:: jinja
+
+    {% include '@theme/header.twig' %}