symfony
diff --git a/‎book/controller.rst
+2-2 b/‎book/controller.rst
+2-2
diff --git a/‎book/from_flat_php_to_symfony2.rst
+1-1 b/‎book/from_flat_php_to_symfony2.rst
+1-1
diff --git a/‎book/http_cache.rst
+4-5 b/‎book/http_cache.rst
+4-5
diff --git a/‎book/http_fundamentals.rst
+10-10 b/‎book/http_fundamentals.rst
+10-10
diff --git a/‎book/page_creation.rst
+2-4 b/‎book/page_creation.rst
+2-4
diff --git a/‎book/propel.rst
+31-31 b/‎book/propel.rst
+31-31
diff --git a/‎book/security.rst
+20-1 b/‎book/security.rst
+20-1
@@ -119,7 +119,7 @@ This controller is pretty straightforward:
 
 * *line 4*: Symfony2 takes advantage of PHP 5.3 namespace functionality to
   namespace the entire controller class. The ``use`` keyword imports the
-  ``Response`` class, which our controller must return.
+  ``Response`` class, which the controller must return.
 
 * *line 6*: The class name is the concatenation of a name for the controller
   class (i.e. ``Hello``) and the word ``Controller``. This is a convention
@@ -218,7 +218,7 @@ passed to that method::
     }
 
 The controller has a single argument, ``$name``, which corresponds to the
-``{name}`` parameter from the matched route (``ryan`` in our example). In
+``{name}`` parameter from the matched route (``ryan`` in the example). In
 fact, when executing your controller, Symfony2 matches each argument of
 the controller with a parameter from the matched route. Take the following
 example:
 
@@ -131,7 +131,7 @@ is known as a "controller". The term :term:`controller` is a word you'll hear
 a lot, regardless of the language or framework you use. It refers simply
 to the area of *your* code that processes user input and prepares the response.
 
-In this case, our controller prepares data from the database and then includes
+In this case, the controller prepares data from the database and then includes
 a template to present that data. With the controller isolated, you could
 easily change *just* the template file if you needed to render the blog
 entries in some other format (e.g. ``list.json.php`` for JSON format).
 
@@ -413,7 +413,7 @@ on a cache to store and return "fresh" responses.
 
     The HTTP specification defines a simple but powerful language in which
     clients and servers can communicate. As a web developer, the request-response
-    model of the specification dominates our work. Unfortunately, the actual
+    model of the specification dominates your work. Unfortunately, the actual
     specification document - `RFC 2616`_ - can be difficult to read.
 
     There is an on-going effort (`HTTP Bis`_) to rewrite the RFC 2616. It does
@@ -553,8 +553,7 @@ would return. An ``ETag`` is like a fingerprint and is used to quickly compare
 if two different versions of a resource are equivalent. Like fingerprints,
 each ``ETag`` must be unique across all representations of the same resource.
 
-Let's walk through a simple implementation that generates the ETag as the
-md5 of the content::
+To see a simple implementation, generate the ETag as the md5 of the content::
 
     public function indexAction()
     {
@@ -871,7 +870,7 @@ independent of the rest of the page.
     }
 
 In this example, the full-page cache has a lifetime of ten minutes.
-Next, let's include the news ticker in the template by embedding an action.
+Next, include the news ticker in the template by embedding an action.
 This is done via the ``render`` helper (See :ref:`templating-embedding-controller`
 for more details).
 
@@ -892,7 +891,7 @@ By setting ``standalone`` to ``true``, you tell Symfony2 that the action
 should be rendered as an ESI tag. You might be wondering why you would want to
 use a helper instead of just writing the ESI tag yourself. That's because
 using a helper makes your application work even if there is no gateway cache
-installed. Let's see how it works.
+installed.
 
 When standalone is ``false`` (the default), Symfony2 merges the included page
 content within the main one before sending the response to the client. But
 
@@ -118,7 +118,7 @@ from the xkcd web server:
    :align: center
 
 Translated into HTTP, the response sent back to the browser will look something
-like this: 
+like this:
 
 .. code-block:: text
 
@@ -145,7 +145,7 @@ known as HTTP headers. For example, one important HTTP response header is
 ``Content-Type``. The body of the same resource could be returned in multiple
 different formats like HTML, XML, or JSON and the ``Content-Type`` header uses
 Internet Media Types like ``text/html`` to tell the client which format is
-being returned. A list of common media types can be found on Wikipedia's 
+being returned. A list of common media types can be found on Wikipedia's
 `List of common media types`_ article.
 
 Many other headers exist, some of which are very powerful. For example, certain
@@ -259,17 +259,17 @@ the user is connecting via a secured connection (i.e. ``https``).
     :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::all` and more.
     In fact, every public property used in the previous example is some instance
     of the ParameterBag.
-    
+
     .. _book-fundamentals-attributes:
-    
+
     The Request class also has a public ``attributes`` property, which holds
     special data related to how the application works internally. For the
     Symfony2 framework, the ``attributes`` holds the values returned by the
     matched route, like ``_controller``, ``id`` (if you have an ``{id}``
     wildcard), and even the name of the matched route (``_route``). The
     ``attributes`` property exists entirely to be a place where you can
     prepare and store context-specific information about the request.
-    
+
 
 Symfony also provides a ``Response`` class: a simple PHP representation of
 an HTTP response message. This allows your application to use an object-oriented
@@ -400,7 +400,7 @@ with many other tools Symfony makes available - to create and return a ``Respons
 object. In other words, the controller is where *your* code goes: it's where
 you interpret the request and create a response.
 
-It's that easy! Let's review:
+It's that easy! To review:
 
 * Each request executes a front controller file;
 
@@ -413,7 +413,7 @@ It's that easy! Let's review:
 A Symfony Request in Action
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Without diving into too much detail, let's see this process in action. Suppose
+Without diving into too much detail, here is this process in action. Suppose
 you want to add a ``/contact`` page to your Symfony application. First, start
 by adding an entry for ``/contact`` to your routing configuration file:
 
@@ -465,14 +465,14 @@ specific PHP method ``contactAction`` inside a class called ``MainController``::
         }
     }
 
-In this very simple example, the controller simply creates a 
-:class:`Symfony\\Component\\HttpFoundation\\Response` object with the HTML 
+In this very simple example, the controller simply creates a
+:class:`Symfony\\Component\\HttpFoundation\\Response` object with the HTML
 "``<h1>Contact us!</h1>"``. In the :doc:`controller chapter</book/controller>`,
 you'll learn how a controller can render templates, allowing your "presentation"
 code (i.e. anything that actually writes out HTML) to live in a separate
 template file. This frees up the controller to worry only about the hard
 stuff: interacting with the database, handling submitted data, or sending
-email messages. 
+email messages.
 
 Symfony2: Build your App, not your Tools.
 -----------------------------------------
 
@@ -22,15 +22,13 @@ HTTP response.
 Symfony2 follows this philosophy and provides you with tools and conventions
 to keep your application organized as it grows in users and complexity.
 
-Sounds simple enough? Let's dive in!
-
 .. index::
    single: Page creation; Example
 
 The "Hello Symfony!" Page
 -------------------------
 
-Let's start with a spin off of the classic "Hello World!" application. When
+Start by building a spin-off of the classic "Hello World!" application. When
 you're finished, the user will be able to get a personal greeting (e.g. "Hello Symfony")
 by going to the following URL:
 
@@ -347,7 +345,7 @@ controller, and ``index.html.twig`` the template:
 
         Hello <?php echo $view->escape($name) ?>!
 
-Let's step through the Twig template line-by-line:
+Step through the Twig template line-by-line:
 
 * *line 2*: The ``extends`` token defines a parent template. The template
   explicitly defines a layout file inside of which it will be placed.
 
@@ -4,7 +4,7 @@
 Databases and Propel
 ====================
 
-Let's face it, one of the most common and challenging tasks for any application
+One of the most common and challenging tasks for any application
 involves persisting and reading information to and from a database. Symfony2
 does not come integrated with any ORMs but the Propel integration is easy.
 To get started, read `Working With Symfony2`_.
@@ -18,8 +18,8 @@ persist it to the database and fetch it back out.
 .. sidebar:: Code along with the example
 
     If you want to follow along with the example in this chapter, create an
-    ``AcmeStoreBundle`` via: 
-    
+    ``AcmeStoreBundle`` via:
+
     .. code-block:: bash
 
         $ php app/console generate:bundle --namespace=Acme/StoreBundle
@@ -171,19 +171,19 @@ Fetching Objects from the Database
 Fetching an object back from the database is even easier. For example, suppose
 you've configured a route to display a specific ``Product`` based on its ``id``
 value::
-    
+
     // ...
     use Acme\StoreBundle\Model\ProductQuery;
-    
+
     public function showAction($id)
     {
         $product = ProductQuery::create()
             ->findPk($id);
-    
+
         if (!$product) {
             throw $this->createNotFoundException('No product found for id '.$id);
         }
-    
+
         // ... do something, like pass the $product object into a template
     }
 
@@ -192,22 +192,22 @@ Updating an Object
 
 Once you've fetched an object from Propel, updating it is easy. Suppose you
 have a route that maps a product id to an update action in a controller::
-    
+
     // ...
     use Acme\StoreBundle\Model\ProductQuery;
-    
+
     public function updateAction($id)
     {
         $product = ProductQuery::create()
             ->findPk($id);
-    
+
         if (!$product) {
             throw $this->createNotFoundException('No product found for id '.$id);
         }
-    
+
         $product->setName('New product name!');
         $product->save();
-    
+
         return $this->redirect($this->generateUrl('homepage'));
     }
 
@@ -227,12 +227,12 @@ method on the object::
 
 Querying for Objects
 --------------------
-    
+
 Propel provides generated ``Query`` classes to run both basic and complex queries
 without any work::
-    
+
     \Acme\StoreBundle\Model\ProductQuery::create()->findPk($id);
-    
+
     \Acme\StoreBundle\Model\ProductQuery::create()
         ->filterByName('Foo')
         ->findOne();
@@ -287,13 +287,13 @@ Start by adding the ``category`` definition in your ``schema.xml``:
             <column name="name" type="varchar" primaryString="true" size="100" />
             <column name="price" type="decimal" />
             <column name="description" type="longvarchar" />
-    
+
             <column name="category_id" type="integer" />
             <foreign-key foreignTable="category">
                 <reference local="category_id" foreign="id" />
             </foreign-key>
         </table>
-    
+
         <table name="category">
             <column name="id" type="integer" required="true" primaryKey="true" autoIncrement="true" />
             <column name="name" type="varchar" primaryString="true" size="100" />
@@ -320,29 +320,29 @@ Your database has been updated, you can continue to write your application.
 Saving Related Objects
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Now, let's see the code in action. Imagine you're inside a controller::
+Now, try the code in action. Imagine you're inside a controller::
 
     // ...
     use Acme\StoreBundle\Model\Category;
     use Acme\StoreBundle\Model\Product;
     use Symfony\Component\HttpFoundation\Response;
-    
+
     class DefaultController extends Controller
     {
         public function createProductAction()
         {
             $category = new Category();
             $category->setName('Main Products');
-    
+
             $product = new Product();
             $product->setName('Foo');
             $product->setPrice(19.99);
             // relate this product to the category
             $product->setCategory($category);
-    
+
             // save the whole
             $product->save();
-    
+
             return new Response(
                 'Created product id: '.$product->getId().' and category id: '.$category->getId()
             );
@@ -363,15 +363,15 @@ before.  First, fetch a ``$product`` object and then access its related
 
     // ...
     use Acme\StoreBundle\Model\ProductQuery;
-    
+
     public function showAction($id)
     {
         $product = ProductQuery::create()
             ->joinWithCategory()
             ->findPk($id);
-    
+
         $categoryName = $product->getCategory()->getName();
-    
+
         // ...
     }
 
@@ -395,7 +395,7 @@ inserted, updated, deleted, etc).
 To add a hook, just add a new method to the object class::
 
     // src/Acme/StoreBundle/Model/Product.php
-    
+
     // ...
     class Product extends BaseProduct
     {
@@ -429,8 +429,8 @@ Commands
 
 You should read the dedicated section for `Propel commands in Symfony2`_.
 
-.. _`Working With Symfony2`: http://www.propelorm.org/cookbook/symfony2/working-with-symfony2.html#installation
-.. _`Working With Symfony2 - Configuration`: http://www.propelorm.org/cookbook/symfony2/working-with-symfony2.html#configuration
-.. _`Relationships`: http://www.propelorm.org/documentation/04-relationships.html
-.. _`Behaviors reference section`: http://www.propelorm.org/documentation/#behaviors_reference
-.. _`Propel commands in Symfony2`: http://www.propelorm.org/cookbook/symfony2/working-with-symfony2#the_commands
+.. _`Working With Symfony2`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#installation
+.. _`Working With Symfony2 - Configuration`: http://propelorm.org/cookbook/symfony2/working-with-symfony2.html#configuration
+.. _`Relationships`: http://propelorm.org/documentation/04-relationships.html
+.. _`Behaviors reference section`: http://propelorm.org/documentation/#behaviors_reference
+.. _`Propel commands in Symfony2`: http://propelorm.org/cookbook/symfony2/working-with-symfony2#the_commands
@@ -20,7 +20,8 @@ perform a certain action.
 .. image:: /images/book/security_authentication_authorization.png
    :align: center
 
-Since the best way to learn is to see an example, let's dive right in.
+Since the best way to learn is to see an example, start by securing your
+application with HTTP Basic authentication.
 
 .. note::
 
@@ -1701,6 +1702,24 @@ To switch back to the original user, use the special ``_exit`` username:
 
     http://example.com/somewhere?_switch_user=_exit
 
+During impersonation, the user is provided with a special role called
+``ROLE_PREVIOUS_ADMIN``. In a template, for instance, this role can be used
+to show a link to exit impersonation:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {% if is_granted('ROLE_PREVIOUS_ADMIN') %}
+            <a href="{{ path('homepage', {_switch_user: '_exit'}) }}">Exit impersonation</a>
+        {% endif %}
+
+    .. code-block:: html+php
+
+        <?php if ($view['security']->isGranted('ROLE_PREVIOUS_ADMIN')): ?>
+            <a href="<?php echo $view['router']->generate('homepage', array('_switch_user' => '_exit') ?>">Exit impersonation</a>
+        <?php endif; ?>
+
 Of course, this feature needs to be made available to a small group of users.
 By default, access is restricted to users having the ``ROLE_ALLOWED_TO_SWITCH``
 role. The name of this role can be modified via the ``role`` setting. For