made some new changes, corrected mistakes, undo some foolish deletions

- added a few new subtitles in the first three chapters
- reordered couple of titles for better flow

Author: talitakz

book/from_flat_php_to_symfony2.rst

@@ -9,7 +9,7 @@ Symfony versus Flat PHP
 **Why is Symfony better than just opening up a file and writing flat PHP?**
 
 If you've never used a PHP framework, aren't familiar with the
-model-view-controller `MVC`_ philosophy, or just wonder what all the *hype*
+`Model-View-Controller`_ (MVC) philosophy, or just wonder what all the *hype*
 is around Symfony, this chapter is for you. Instead of *telling* you that
 Symfony allows you to develop faster and better software than with flat PHP,
 you'll see for yourself.
@@ -27,7 +27,7 @@ A Simple Blog in Flat PHP
 
 In this chapter, you'll build the token blog application using only flat PHP.
 To begin, create a single page that displays blog entries that have been
-persisted to the database. Writing in flat PHP is quick and dirty:
+persisted to the database. Writing in flat PHP is quick and dirty::
 
 .. code-block:: html+php
 
@@ -102,8 +102,8 @@ the code that prepares the HTML "presentation"::
     require 'templates/list.php';
 
 
-The HTML code is now stored in a separate file (``templates/list.php``), which
-is primarily an HTML file that uses a template-like PHP syntax:
+The HTML code is now stored in a separate file ``templates/list.php``, which
+is primarily an HTML file that uses a template-like PHP syntax::
 
 .. code-block:: html+php
 
@@ -203,7 +203,7 @@ offering various advantages and the opportunity to reuse almost everything
 on different pages.
 
 The only part of the code that *can't* be reused is the page layout. Fix
-that by creating a new ``templates/layout.php`` file:
+that by creating a new ``templates/layout.php`` file::
 
 .. code-block:: html+php
 
@@ -218,8 +218,8 @@ that by creating a new ``templates/layout.php`` file:
         </body>
     </html>
 
-The template (``templates/list.php``) can now be simplified to "extend"
-the layout:
+The template ``templates/list.php`` can now be simplified to "extend"
+the ``templates/layout.php``::
 
 .. code-block:: html+php
 
@@ -256,7 +256,7 @@ and reusable. To prove it, add a blog "show" page, which displays an individual
 blog post identified by an ``id`` query parameter.
 
 To begin, create a new function in the ``model.php`` file that retrieves
-an individual blog result based on a given ``id``::
+an individual blog result based on a given id::
 
     // model.php
     function get_post_by_id($id)
@@ -286,7 +286,7 @@ page::
     require 'templates/show.php';
 
 Finally, create the new template file - ``templates/show.php`` - to render
-the individual blog post:
+the individual blog post::
 
 .. code-block:: html+php
 
@@ -378,7 +378,7 @@ For organization, both controllers (formerly ``index.php`` and ``show.php``)
 are now PHP functions and each has been moved into a separate file named
 ``controllers.php``. The job of each PHP function, now called a
 :term:`controller`, is to use information from the ``Request`` object to create
-and return a ``Response`` object.::
+and return a ``Response`` object::
 
     // controllers.php
     function list_action()
@@ -417,13 +417,15 @@ act a lot like Symfony's mechanism for handling and routing requests.
 By now, the application has evolved from a single PHP file into a structure
 that is organized and allows for code reuse. You should be happier, but far
 from satisfied. For example, the routing system is fickle, and wouldn't
-recognize that the list page (``/index.php``) should be accessible also via ``/``
+recognize that the list page - ``/index.php``  - should be accessible also via ``/``
 (if Apache rewrite rules were added). Also, instead of developing the blog,
 a lot of time is being spent working on the "architecture" of the code (e.g.
 routing, calling controllers, templates, etc.). More time will need to be
 spent to handle form submissions, input validation, logging and security.
 Why should you have to reinvent solutions to all these routine problems?
 
+.. _add-a-touch-of-symfony2:
+
 Add a Touch of Symfony
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -434,7 +436,7 @@ autoloader is a tool that makes it possible to start using PHP classes
 without explicitly including the file containing the class.
 
 In your root directory, create a ``composer.json`` file with the following
-content:
+content::
 
 .. code-block:: json
 
@@ -522,7 +524,8 @@ incidentally, acts quite a bit like the Symfony templating engine::
 
 By bringing in a small part of Symfony, the application is more flexible and
 reliable. The ``Request`` provides a dependable way to access information
-about the HTTP request. Specifically, the ``getPathInfo()`` method returns
+about the HTTP request. Specifically, the
+:method:`Symfony\\Component\\HttpFoundation\\Request::getPathInfo` method returns
 a cleaned URI (always returning ``/show`` and never ``/index.php/show``).
 So, even if the user goes to ``/index.php/show``, the application is intelligent
 enough to route the request through ``show_action()``.
@@ -588,7 +591,7 @@ also called *actions*. They hold code which creates and returns the appropriate
 The two controllers are still lightweight. Each uses the
 :doc:`Doctrine ORM library </book/doctrine>` to retrieve objects from the
 database and the Templating component to render a template and return a
-``Response`` object. The list (``list.php``) template is now quite a bit simpler:
+``Response`` object. The list ``list.php`` template is now quite a bit simpler::
 
 .. code-block:: html+php
 
@@ -611,7 +614,7 @@ database and the Templating component to render a template and return a
         <?php endforeach ?>
     </ul>
 
-The layout (``layout.php``) is nearly identical:
+The layout ``layout.php`` is nearly identical::
 
 .. code-block:: html+php
 
@@ -631,13 +634,13 @@ The layout (``layout.php``) is nearly identical:
 
 .. note::
 
-    The show (``show.php``) template is left as an exercise, as it should be trivial to
-    create based on the list (``list.php``) template.
+    The show ``show.php`` template is left as an exercise, as it should be trivial to
+    create based on the list ``list.php`` template.
 
 When Symfony's engine (called the :term:`Kernel`) boots up, it needs a map so
 that it knows which controllers to execute based on the request information.
 A routing configuration map ``app/config/routing.yml`` provides this information
-in a readable format:
+in a readable format::
 
 .. code-block:: yaml
 
@@ -677,47 +680,14 @@ object are sent back to the client.
    :align: center
    :alt: Symfony request flow
 
-Where Symfony Delivers
-~~~~~~~~~~~~~~~~~~~~~~
-
-In the upcoming chapters, you'll learn more about how each piece of Symfony
-works and the recommended organization of a project. For now, have a look
-at how migrating the blog from flat PHP to Symfony has improved life:
-
-* Your application now has **clear and consistently organized code** (though
-  Symfony doesn't force you into this). This promotes **reusability** and
-  allows for new developers to be productive in your project more quickly;
-
-* 100% of the code you write is for *your* application. You **don't need
-  to develop or maintain low-level utilities** such as autoloading,
-  :doc:`routing </book/routing>`, or rendering :doc:`controllers </book/controller>`;
-
-* Symfony gives you **access to open source tools** such as `Doctrine`_ and the
-  :doc:`Templating </components/templating/introduction>`,
-  :doc:`Security </components/security/introduction>`,
-  :doc:`Form </components/form/introduction>`, `Validator`_ and
-  :doc:`Translation </components/translation/introduction>` components (to name
-  a few);
-
-* The application now enjoys **fully-flexible URLs** thanks to the Routing
-  component;
-
-* Symfony's HTTP-centric architecture gives you access to powerful tools
-  such as **HTTP caching** powered by **Symfony's internal HTTP cache** or
-  more powerful tools such as `Varnish`_. This is covered in a later chapter
-  all about :doc:`caching </book/http_cache>`.
-
-And perhaps best of all, by using Symfony, you now have access to a whole
-set of **high-quality open source tools developed by the Symfony community**!
-A good selection of Symfony community tools can be found on `KnpBundles.com`_.
-
-Better Templates
-----------------
+PHP Templates versus Twig Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you choose to use it, Symfony comes standard with a templating engine
 called `Twig`_ that makes templates faster to write and easier to read.
 It means that the sample application could contain even less code! Take,
-for example, lets rewrite ``layout.html.php`` template in Twig:
+for example, rewriting ``list.html.php`` template in Twig would look like
+this::
 
 .. code-block:: html+twig
 
@@ -739,7 +709,7 @@ for example, lets rewrite ``layout.html.php`` template in Twig:
         </ul>
     {% endblock %}
 
-The corresponding ``layout.html.php`` template is also easier to write in Twig:
+And rewriting ``layout.html.php`` template in Twig would look like this::
 
 .. code-block:: html+twig
 
@@ -758,14 +728,49 @@ Twig is well-supported in Symfony. And while PHP templates will always
 be supported in Symfony, the many advantages of Twig will continue to
 be discussed. For more information, see the :doc:`templating chapter </book/templating>`.
 
+
+Where Symfony Delivers
+----------------------
+
+In the upcoming chapters, you'll learn more about how each piece of Symfony
+works and the recommended organization of a project. For now, have a look
+at how migrating the blog from flat PHP to Symfony has improved life:
+
+* Your application now has **clear and consistently organized code** (though
+  Symfony doesn't force you into this). This promotes **reusability** and
+  allows for new developers to be productive in your project more quickly;
+
+* 100% of the code you write is for *your* application. You **don't need
+  to develop or maintain low-level utilities** such as autoloading,
+  :doc:`routing </book/routing>`, or rendering :doc:`controllers </book/controller>`;
+
+* Symfony gives you **access to open source tools** such as `Doctrine`_ and the
+  :doc:`Templating </components/templating/introduction>`,
+  :doc:`Security </components/security/introduction>`,
+  :doc:`Form </components/form/introduction>`, `Validator`_ and
+  :doc:`Translation </components/translation/introduction>` components (to name
+  a few);
+
+* The application now enjoys **fully-flexible URLs** thanks to the Routing
+  component;
+
+* Symfony's HTTP-centric architecture gives you access to powerful tools
+  such as **HTTP caching** powered by **Symfony's internal HTTP cache** or
+  more powerful tools such as `Varnish`_. This is covered in a later chapter
+  all about :doc:`caching </book/http_cache>`.
+
+And perhaps best of all, by using Symfony, you now have access to a whole
+set of **high-quality open source tools developed by the Symfony community**!
+A good selection of Symfony community tools can be found on `KnpBundles.com`_.
+
 Learn more from the Cookbook
 ----------------------------
 
 * :doc:`/cookbook/templating/PHP`
 * :doc:`/cookbook/controller/service`
 
 
-.. _`MVC`: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
+.. _`Model-View-Controller`: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller
 .. _`Doctrine`: http://www.doctrine-project.org
 .. _`SQL injection attack`: https://en.wikipedia.org/wiki/SQL_injection
 .. _`Composer`: https://getcomposer.org