Reworded and improved the routing/external_resources article

Author: javiereguiluz

routing/external_resources.rst

@@ -4,19 +4,37 @@
 How to Include External Routing Resources
 =========================================
 
-All routes are loaded via a single configuration file - usually ``app/config/routing.yml``
-(see :ref:`routing-creating-routes`). However, if you use routing annotations,
-you'll need to point the router to the controllers with the annotations.
-This can be done by "importing" directories into the routing configuration:
+Simple applications can define all their routes in a single configuration file -
+usually ``app/config/routing.yml`` (see :ref:`routing-creating-routes`).
+However, in most applications it's common to import routes definitions from
+different resources: PHP annotations in controller files, YAML or XML files
+stored in some directory, etc.
+
+This can be done by importing routing resources from the main routing file:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # app/config/routing.yml
-        app:
+        app_file:
+            # loads routes from the given routing file stored in some bundle
+            resource: '@AcmeOtherBundle/Resources/config/routing.yml'
+
+        app_annotations:
+            # loads routes from the PHP annotations of the controllers found in that directory
             resource: '@AppBundle/Controller/'
-            type:     annotation # required to enable the Annotation reader for this resource
+            type:     annotation
+
+        app_directory:
+            # loads routes from the YAML or XML files found in that directory
+            resource: '../legacy/routing/'
+            type:     directory
+
+        app_bundle:
+            # loads routes from the YAML or XML files found in some bundle directory
+            resource: '@AppBundle/Resources/config/routing/public/'
+            type:     directory
 
     .. code-block:: xml
 
@@ -27,8 +45,17 @@ This can be done by "importing" directories into the routing configuration:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <!-- the type is required to enable the annotation reader for this resource -->
-            <import resource="@AppBundle/Controller/" type="annotation"/>
+            <!-- loads routes from the given routing file stored in some bundle -->
+            <import resource="@AcmeOtherBundle/Resources/config/routing.yml" />
+
+            <!-- loads routes from the PHP annotations of the controllers found in that directory -->
+            <import resource="@AppBundle/Controller/" type="annotation" />
+
+            <!-- loads routes from the YAML or XML files found in that directory -->
+            <import resource="../legacy/routing/" type="directory" />
+
+            <!-- loads routes from the YAML or XML files found in some bundle directory -->
+            <import resource="@AppBundle/Resources/config/routing/public/" type="directory" />
         </routes>
 
     .. code-block:: php
@@ -38,60 +65,26 @@ This can be done by "importing" directories into the routing configuration:
 
         $collection = new RouteCollection();
         $collection->addCollection(
-            // second argument is the type, which is required to enable
-            // the annotation reader for this resource
+            // loads routes from the given routing file stored in some bundle
+            $loader->import("@AcmeOtherBundle/Resources/config/routing.yml")
+
+            // loads routes from the PHP annotations of the controllers found in that directory
             $loader->import("@AppBundle/Controller/", "annotation")
+
+            // loads routes from the YAML or XML files found in that directory
+            $loader->import("../legacy/routing/", "directory")
+
+            // loads routes from the YAML or XML files found in some bundle directory
+            $loader->import("@AppBundle/Resources/config/routing/public/", "directory")
         );
 
         return $collection;
 
 .. note::
 
-    When importing resources from YAML, the key (e.g. ``app``) is meaningless.
+    When importing resources from YAML, the key (e.g. ``app_file``) is meaningless.
     Just be sure that it's unique so no other lines override it.
 
-The ``resource`` key loads the given routing resource. In this example the
-resource is a directory, where the ``@AppBundle`` shortcut syntax resolves
-to the full path of the AppBundle. When pointing to a directory, all files
-in that directory are parsed and put into the routing.
-
-.. note::
-
-    You can also include other routing configuration files, this is often
-    used to import the routing of third party bundles:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # app/config/routing.yml
-            app:
-                resource: '@AcmeOtherBundle/Resources/config/routing.yml'
-
-        .. code-block:: xml
-
-            <!-- app/config/routing.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <routes xmlns="http://symfony.com/schema/routing"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xsi:schemaLocation="http://symfony.com/schema/routing
-                    http://symfony.com/schema/routing/routing-1.0.xsd">
-
-                <import resource="@AcmeOtherBundle/Resources/config/routing.xml" />
-            </routes>
-
-        .. code-block:: php
-
-            // app/config/routing.php
-            use Symfony\Component\Routing\RouteCollection;
-
-            $collection = new RouteCollection();
-            $collection->addCollection(
-                $loader->import("@AcmeOtherBundle/Resources/config/routing.php")
-            );
-
-            return $collection;
-
 Prefixing Imported Routes
 ~~~~~~~~~~~~~~~~~~~~~~~~~