More fixes suggested by Ryan

Author: javiereguiluz

routing.rst

@@ -4,11 +4,11 @@
 Routing
 =======
 
-When your application receives an HTTP request, it executes a
-:doc:`controller action </controller>` to generate the HTTP response. The
-routing configuration defines which action to run for each incoming URL. It also
-provides other useful features, like generating SEO-friendly URLs
-(e.g. ``/read/intro-to-symfony`` instead of ``index.php?article_id=57``).
+When your application receives a request, it executes a
+:doc:`controller action </controller>` to generate the response. The routing
+configuration defines which action to run for each incoming URL. It also
+provides other useful features, like generating SEO-friendly URLs (e.g.
+``/read/intro-to-symfony`` instead of ``index.php?article_id=57``).
 
 Creating Routes
 ---------------
@@ -332,47 +332,41 @@ with a locale. This can be done by defining a different prefix for each locale
 Route Groups
 ~~~~~~~~~~~~
 
-It's common for a group of routes to share some options (e.g. all routes
-related to the blog start with ``/blog``; all routes validate the locale with
-the same regular expression; etc.) That's why Symfony includes a feature to
-share route configuration.
+It's common for a group of routes to share some options (e.g. all routes related
+to the blog start with ``/blog``) That's why Symfony includes a feature to share
+route configuration.
 
-When defining routes as annotations, add an ``@Route`` annotation to the
-controller class to apply options to all the routes defined in that class::
+When defining routes as annotations, put the common configuration in the
+``@Route`` annotation of the controller class. In other routing formats, define
+the common configuration using options when importing the routes.
 
-    use Symfony\Component\Routing\Annotation\Route;
+.. configuration-block::
 
-    /**
-     * @Route("/blog", requirements={"locale": "en|es|fr"}, name="blog_")
-     */
-    class BlogController
-    {
-        /**
-         * @Route("/{_locale}", name="index")
-         */
-        public function index()
-        {
-            // ...
-        }
+    .. code-block:: php-annotations
+
+        use Symfony\Component\Routing\Annotation\Route;
 
         /**
-         * @Route("/{_locale}/posts/{slug}", name="post")
+         * @Route("/blog", requirements={"locale": "en|es|fr"}, name="blog_")
          */
-        public function show(Post $post)
+        class BlogController
         {
-            // ...
-        }
-    }
-
-In this example, the route of the ``index()`` action will be called ``blog_index``
-and its URL will be ``/blog/``. The route of the ``show()`` action will be called
-``blog_post`` and its URL will be ``/blog/{_locale}/posts/{slug}``. Both routes
-will also validate that the ``_locale`` parameter matches the regular expression
-defined in the class annotation.
-
-The same can be used when importing routes from configuration files:
+            /**
+             * @Route("/{_locale}", name="index")
+             */
+            public function index()
+            {
+                // ...
+            }
 
-.. configuration-block::
+            /**
+             * @Route("/{_locale}/posts/{slug}", name="post")
+             */
+            public function show(Post $post)
+            {
+                // ...
+            }
+        }
 
     .. code-block:: yaml
 
@@ -387,6 +381,9 @@ The same can be used when importing routes from configuration files:
             # these requirements are added to all imported routes
             requirements:
                 locale: 'en|es|fr'
+            # An imported route with an empty URL will become "/blog/"
+            # Uncomment this option to make that URL "/blog" instead
+            # trailing_slash_on_root: false
 
     .. code-block:: xml
 
@@ -397,14 +394,25 @@ The same can be used when importing routes from configuration files:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <import resource="../src/Controller/" type="annotation">
-                <!-- this is added to the beginning of all imported route URLs -->
-                <prefix>/blog</prefix>
-                <!-- this is added to the beginning of all imported route names -->
-                <name-prefix>blog_</name-prefix>
+            <!--
+                the 'prefix' value is added to the beginning of all imported route URLs
+                the 'name-prefix' value is added to the beginning of all imported route names
+            -->
+            <import resource="../src/Controller/"
+                type="annotation"
+                prefix="/blog"
+                name-prefix="blog_">
                 <!-- these requirements are added to all imported routes -->
                 <requirement key="locale">en|es|fr</requirement>
             </import>
+
+            <!-- An imported route with an empty URL will become "/blog/"
+                 Uncomment this option to make that URL "/blog" instead -->
+            <import resource="../src/Controller/" type="annotation"
+                    prefix="/blog"
+                    trailing-slash-on-root="false">
+                    <!-- ... -->
+            </import>
         </routes>
 
     .. code-block:: php
@@ -416,58 +424,21 @@ The same can be used when importing routes from configuration files:
             $routes->import('../src/Controller/', 'annotation')
                 // this is added to the beginning of all imported route URLs
                 ->prefix('/blog')
+                // An imported route with an empty URL will become "/blog/"
+                // Pass FALSE as the second argument to make that URL "/blog" instead
+                // ->prefix('/blog', false)
                 // this is added to the beginning of all imported route names
                 ->namePrefix('blog_')
                 // these requirements are added to all imported routes
                 ->requirements(['locale' => 'en|es|fr'])
             ;
         };
 
-.. note::
-
-    If any of the prefixed routes defines an empty path, Symfony adds a trailing
-    slash to it. In the previous example, an empty path prefixed with ``/site``
-    will result in the ``/site/`` URL. If you want to avoid this behavior, set
-    the ``trailing_slash_on_root`` option to ``false``:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/routes.yaml
-            controllers:
-                resource: '../src/Controller/'
-                type:     annotation
-                prefix:   /blog
-                trailing_slash_on_root: false
-
-        .. code-block:: xml
-
-            <!-- config/routes.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
-                    https://symfony.com/schema/routing/routing-1.0.xsd">
-
-                <import resource="../src/Controller/"
-                    type="annotation"
-                    prefix="/blog"
-                    trailing-slash-on-root="false"/>
-            </routes>
-
-        .. code-block:: php
-
-            // config/routes.php
-            use App\Controller\ArticleController;
-            use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
-
-            return function (RoutingConfigurator $routes) {
-                $routes->import('../src/Controller/', 'annotation')
-                    // the second argument is a boolean to configure 'trailing_slash_on_root'
-                    ->prefix('/blog', false)
-                ;
-            };
+In this example, the route of the ``index()`` action will be called ``blog_index``
+and its URL will be ``/blog/``. The route of the ``show()`` action will be called
+``blog_post`` and its URL will be ``/blog/{_locale}/posts/{slug}``. Both routes
+will also validate that the ``_locale`` parameter matches the regular expression
+defined in the class annotation.
 
 .. seealso::