feature #5856 Reworded the "How to use Gmail" cookbook article (javiereguiluz)

This PR was squashed before being merged into the 2.3 branch (closes #5856).

Discussion
----------

Reworded the "How to use Gmail" cookbook article

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | -

In StackOverflow some people are [having issues](http://stackoverflow.com/questions/33226583/swiftmailer-doesnt-work/33240538#33240538) with the `encryption` parameter of Gmail. And others are [having issues](symfony/swiftmailer-bundle#106) with Gmail + SwiftMailerBundle.

That's why I propose to reword this article and explain some things with more detail.

Commits
-------

b113f72 Reworded the "How to use Gmail" cookbook article

Author: wouterj

cookbook/email/gmail.rst

@@ -8,11 +8,6 @@ During development, instead of using a regular SMTP server to send emails, you
 might find using Gmail easier and more practical. The SwiftmailerBundle makes
 it really easy.
 
-.. tip::
-
-    Instead of using your regular Gmail account, it's of course recommended
-    that you create a special account.
-
 In the development configuration file, change the ``transport`` setting to
 ``gmail`` and set the ``username`` and ``password`` to the Google credentials:
 
@@ -55,33 +50,84 @@ In the development configuration file, change the ``transport`` setting to
             'password'  => 'your_gmail_password',
         ));
 
-You're done!
+If you are using the Symfony Standard Edition, it's more convenient to configure
+these options in the ``parameters.yml.dist`` file:
 
-.. tip::
+.. code-block:: yaml
 
-    If you are using the Symfony Standard Edition, configure the parameters in ``parameters.yml``:
+    # app/config/parameters.yml.dist
+    parameters:
+        # ...
+        mailer_user:      your_gmail_username
+        mailer_password:  your_gmail_password
+
+.. configuration-block::
 
     .. code-block:: yaml
 
-        # app/config/parameters.yml
-        parameters:
-            # ...
-            mailer_transport: gmail
-            mailer_host:      ~
-            mailer_user:      your_gmail_username
-            mailer_password:  your_gmail_password
+        # app/config/config_dev.yml
+        swiftmailer:
+            transport: gmail
+            username:  '%mailer_user%'
+            password:  '%mailer_password%'
+
+    .. code-block:: xml
+
+        <!-- app/config/config_dev.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/swiftmailer
+                http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+            <!-- ... -->
+            <swiftmailer:config
+                transport="gmail"
+                username="%mailer_user%"
+                password="%mailer_password%"
+            />
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config_dev.php
+        $container->loadFromExtension('swiftmailer', array(
+            'transport' => 'gmail',
+            'username'  => '%mailer_user%',
+            'password'  => '%mailer_password%',
+        ));
+
+Redefining the Default Configuration Parameters
+-----------------------------------------------
+
+The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
+and sets these options:
+
+==============  ==================
+Option          Value
+==============  ==================
+``encryption``  ``ssl``
+``auth_mode``   ``login``
+``host``        ``smtp.gmail.com``
+==============  ==================
+
+If your application uses ``tls`` encryption or ``oauth`` authentication, you
+must override the default options by defining the ``encryption`` and ``auth_mode``
+parameters.
 
-.. note::
+If you are using 2-Step-Verification, you must `generate an App password`_ and
+use this as your ``mailer_password`` value.
 
-    The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
-    and sets ``encryption``, ``auth_mode`` and ``host`` to work with Gmail.
+If your Gmail account uses 2-Step-Verification, you must `generate an App password`_
+and use it as the value of the ``mailer_password`` parameter. You must also ensure
+that you `allow less secure apps to access your Gmail account`_.
 
-.. note::
+.. seealso::
 
-    Depending on your Gmail account settings, you may get authentication errors
-    within your app. If your Gmail account uses 2-Step-Verification, you should
-    `generate an App password`_ to use for your ``mailer_password`` parameter.
-    You should also ensure that you `allow less secure apps to access your Gmail account`_.
+    :doc:`Swiftmailer configuration reference </reference/configuration/swiftmailer>`
 
 .. _`generate an App password`: https://support.google.com/accounts/answer/185833
 .. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255