Included a bunch of fixes suggested by the awesome Symfony doc reviewers

symfony · javiereguiluz · Oct 25, 2014 · Oct 25, 2014 · Nov 1, 2014 · Nov 12, 2014
commit 1ca388e47bd30afee30ffd713d3b28933a8f8f36
diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst
@@ -13,7 +13,7 @@ Understanding the Directory Structure
 The directory structure of a Symfony :term:`application` is rather flexible,
 but the recommended structure is as follows:
 
-* ``app/``: the application configuration and templates;
+* ``app/``: the application configuration, templates and translations;
 * ``src/``: the project's PHP code;
 * ``vendor/``: the third-party dependencies;
 * ``web/``: the web root directory.
@@ -121,8 +121,8 @@ a single ``Bundle`` class that describes it::
     }
 
 In addition to the AppBundle that was already talked about, notice that the
-kernel also enables other bundles such as the FrameworkBundle, DoctrineBundle,
-SwiftmailerBundle and AsseticBundle. They are all part of the core framework.
+kernel also enables other bundles that are part of Symfony, such as FrameworkBundle,
+DoctrineBundle, SwiftmailerBundle and AsseticBundle.
 
 Configuring a Bundle
 ~~~~~~~~~~~~~~~~~~~~
@@ -168,7 +168,7 @@ PHP. Have a look at this sample of the default Symfony configuration:
 
     # ...
 
-Each first level entry like ``framework``, ``twig`` or ``swiftmailer`` defines
+Each first level entry like ``framework``, ``twig`` and ``swiftmailer`` defines
 the configuration for a specific bundle. For example, ``framework`` configures
 the FrameworkBundle while ``swiftmailer`` configures the SwiftmailerBundle.
 
@@ -238,10 +238,10 @@ Using Vendors
 -------------
 
 Odds are that your application will depend on third-party libraries. Those
-should be stored in the ``vendor/`` directory and managed by Composer.
-This directory already contains the Symfony libraries, the SwiftMailer library,
-the Doctrine ORM, the Twig templating system and some other third party
-libraries and bundles.
+should be stored in the ``vendor/`` directory. You should never touch anything
+in this directory, because it is exclusively managed by Composer. This directory
+already contains the Symfony libraries, the SwiftMailer library, the Doctrine ORM,
+the Twig templating system and some other third party libraries and bundles.
 
 Understanding the Cache and Logs
 --------------------------------

diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst
@@ -23,10 +23,9 @@ to display the installed PHP version:
 Installing Symfony
 ------------------
 
-In the past, Symfony had to be installed manually for each new project. In order
-to simplify this set up, a new **Symfony Installer** was introduced recently.
-This means that the very first time you use Symfony on a computer, you have to
-install the Symfony Installer.
+In the past, Symfony had to be installed manually for each new project. Now you
+can use the **Symfony Installer**, which has to be installed the very first time
+you use Symfony on a computer.
 
 On **Linux** and **Mac OS X** systems, execute the following console commands:
 
@@ -52,9 +51,15 @@ to be able to execute the new ``symfony`` command:
 
     $ symfony
 
-On **Windows** systems, download the ``symfony.phar`` file from ........... and
-save it into the direc
8000
tory where you create the Symfony projects. Then you can
-execute the Symfony installer right away with this command:
+On **Windows** systems, execute the following console command:
+
+ .. code-block:: bash
+
+    c:\> php -r "readfile('https://symfony.com/installer');" | php
+
+This command downloads a file called ``symfony.phar`` which contains the Symfony
+installer. Save or move that file to the directory where you create the Symfony
+projects and then, execute the Symfony installer right away with this command:
 
 .. code-block:: bash
 
@@ -90,7 +95,7 @@ the project directory and executing this command:
 .. code-block:: bash
 
     $ cd myproject/
-    $ php app/console server:start
+    $ php app/console server:run
 
 Open your browser and access the ``http://localhost:8000`` URL to see the
 Welcome page of Symfony:
@@ -166,9 +171,9 @@ that will be explained in the next section)::
         }
     }
 
-In Symfony applications, **controllers** are PHP classes whose names are suffixed
-with the ``Controller`` word. In this example, the controller is called ``Default``
-and the PHP class is called ``DefaultController``.
+In Symfony applications, **controllers** are usually PHP classes whose names are
+suffixed with the ``Controller`` word. In this example, the controller is called
+``Default`` and the PHP class is called ``DefaultController``.
 
 The methods defined in a controller are called **actions**, they are usually
 associated with one URL of the application and their names are suffixed with
@@ -230,8 +235,9 @@ of the ``Default`` controller when the user browses the ``/`` path of the applic
 .. tip::
 
     In addition to PHP annotations, routes can be configured in YAML, XML or
-    PHP files. This flexibility is one of the main features of Symfony, a
-    framework that never imposes a particular configuration format on you.
+    PHP files, as explained in `the Routing chapter of the Symfony book`_ .
+    This flexibility is one of the main features of Symfony, a framework that
+    never imposes a particular configuration format on you.
 
 Templates
 ~~~~~~~~~
@@ -348,6 +354,7 @@ Symfony makes it really easy to implement web sites better and faster. If you
 are eager to learn more about Symfony, dive into the next section:
 ":doc:`The View <the_view>`".
 
-.. _Composer:             https://getcomposer.org/
+.. _Composer: https://getcomposer.org/
 .. _executable installer: http://getcomposer.org/download
-.. _Twig:                 http://twig.sensiolabs.org/
+.. _Twig: http://twig.sensiolabs.org/
+.. _the Routing chapter of the Symfony book: http://symfony.com/doc/current/book/routing.html
diff --git a/quick_tour/the_controller.rst b/quick_tour/the_controller.rst
@@ -218,6 +218,8 @@ In the case of ``404`` errors, Symfony includes a handy shortcut that you can
 use in your controllers::
 
     // src/AppBundle/Controller/DefaultController.php
+    // ...
+
     class DefaultController extends Controller
     {
         /**
@@ -234,6 +236,8 @@ For ``500`` errors, just throw a regular PHP exception inside the controller and
 Symfony will transform it into a proper ``500`` error page::
 
     // src/AppBundle/Controller/DefaultController.php
+    // ...
+
     class DefaultController extends Controller
     {
         /**

diff --git a/quick_tour/the_view.rst b/quick_tour/the_view.rst
@@ -64,18 +64,18 @@ display the content of a variable passed by the controller depending on its type
 .. code-block:: jinja
 
     {# 1. Simple variables #}
-    {# $this->render( ..., array('name' => 'Fabien') ) #}
+    {# $this->render('template.html.twig', array('name' => 'Fabien') ) #}
     {{ name }}
 
     {# 2. Arrays #}
-    {# $this->render( ..., array('user' => array('name' => 'Fabien')) ) #}
+    {# $this->render('template.html.twig', array('user' => array('name' => 'Fabien')) ) #}
     {{ user.name }}
 
     {# alternative syntax for arrays #}
     {{ user['name'] }}
 
     {# 3. Objects #}
-    {# $this->render( ..., array('user' => new User('Fabien')) ) #}
+    {# $this->render('template.html.twig', array('user' => new User('Fabien')) ) #}
     {{ user.name }}
     {{ user.getName }}
 
@@ -251,7 +251,7 @@ Symfony provides the ``asset`` function to deal with them easily:
     <img src="{{ asset('images/logo.png') }}" />
 
 The ``asset()`` function looks for the web assets inside the ``web/`` directory.
-If you store them in another directory, read :doc:`this article <cookbook/assetic/asset_management>`
+If you store them in another directory, read :doc:`this article </cookbook/assetic/asset_management>`
 to learn how to manage web assets.
 
 Using the ``asset`` function, your application is more portable. The reason is