@@ -1369,7 +1369,7 @@ Some notable or interesting tasks include:
 
 .. code-block:: bash
 
-$ php app/console doctrine:ensure-production-settings --env=prod
+$ php app/console doctrine:ensure-production-settings --env=prod
 
 * ``doctrine:mapping:import`` - allows Doctrine to introspect an existing
 database and create mapping information. For more information, see

@@ -1614,6 +1614,6 @@ Learn more from the Cookbook
 .. _`Symfony2 Form Component`: https://.com/symfony/Form
 .. _`DateTime`: http://php.net/manual/en/class.datetime.php
 .. _`Twig Bridge`: https://.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig
-.. _`form_div_layout.html.twig`: https://.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+.. _`form_div_layout.html.twig`: https://.com/symfony/symfony/blob/2.1/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
 .. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery
 .. _`view on `: https://.com/symfony/symfony/tree/master/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form

@@ -149,6 +149,8 @@ You can also add links to the API documentation:
 
 .. code-block:: rst
 
+:namespace:`Symfony\\Component\\BrowserKit`
+
 :class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`
 
 :method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`

@@ -925,4 +925,28 @@ To render a help message below a field, pass in a ``help`` variable:
 .. tip::
 See :ref:`cookbook-form-theming-methods` for how to apply this customization.
 
-.. _`form_div_layout.html.twig`: https://.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+Using Form Variables
+--------------------
+
+Most of the functions available for rendering different parts of a form (e.g.
+the form widget, form label, form widget, etc) also allow you to make certain
+customizations directly. Look at the following example:
+
+.. configuration-block::
+
+.. code-block:: jinja
+
+{# render a widget, but add a "foo" class to it #}
+{{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}
+
+ .. code-block:: php
+
+<!-- render a widget, but add a "foo" class to it -->
+<?php echo $view['form']->widget($form['name'], array('attr' => array(
+'class' => 'foo',
+))) ?>
+
+The array passed as the second argument contains form "variables". For
+more details about this concept in Twig, see :ref:`twig-reference-form-variables`.
+
+.. _`form_div_layout.html.twig`: https://.com/symfony/symfony/blob/2.1/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig

@@ -771,5 +771,5 @@ For an example, see the ``EntityInitializer`` class inside the Doctrine Bridge.
 
 .. _`Twig's documentation`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
 .. _`Twig official extension repository`: http://.com/fabpot/Twig-extensions
-.. _`KernelEvents`: https://.com/symfony/symfony/blob/2.0/src/Symfony/Component/HttpKernel/KernelEvents.php
+.. _`KernelEvents`: https://.com/symfony/symfony/blob/2.1/src/Symfony/Component/HttpKernel/KernelEvents.php
 .. _`SwiftMailer's Plugin Documentation`: http://swiftmailer.org/docs/plugins.html

@@ -23,6 +23,9 @@ label you want to display as the second argument.
 {{ form_label(form.name, 'Your Name', {'label_attr': {'class': 'foo'}}) }}
 {{ form_label(form.name, null, {'label': 'Your name', 'label_attr': {'class': 'foo'}}) }}
 
+See ":ref:`twig-reference-form-variables`" to learn about the ``variables``
+argument.
+
 form_errors(form.name)
 ----------------------
 
@@ -50,6 +53,11 @@ The second argument to ``form_widget`` is an array of variables. The most
 common variable is ``attr``, which is an array of HTML attributes to apply
 to the HTML widget. In some cases, certain types also have other template-related
 options that can be passed. These are discussed on a type-by-type basis.
+The ``attributes`` are not applied recursively to child fields if you're
+rendering many fields at once (e.g. ``form_widget(form)``).
+
+See ":ref:`twig-reference-form-variables`" to learn more about the ``variables``
+argument.
 
 form_row(form.name, variables)
 ------------------------------
@@ -66,6 +74,9 @@ The second argument to ``form_row`` is an array of variables. The templates
 provided in Symfony only allow to override the label as shown in the example
 above.
 
+See ":ref:`twig-reference-form-variables`" to learn about the ``variables``
+argument.
+
 form_rest(form, variables)
 --------------------------
 
@@ -87,4 +98,75 @@ good idea to include this in your form tag:
 
 .. code-block:: html+jinja
 
-<form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>
+<form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>
+
+.. _`twig-reference-form-variables`:
+
+More about Form "Variables"
+---------------------------
+
+In almost every Twig function above, the final argument is an array of "variables"
+that are used when rendering that one part of the form. For example, the
+following would render the "widget" for a field, and modify its attributes
+to include a special class:
+
+.. code-block:: jinja
+
+{# render a widget, but add a "foo" class to it #}
+{{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}
+
+The purpose of these variables - what they do & where they come from - may
+not be immediately clear, but they're incredibly powerful. Whenever you
+render any part of a form, the block that renders it makes use of a number
+of variables. By default, these blocks live inside `form_div_layout.html.twig`_.
+
+Look at the ``form_label`` as an example:
+
+.. code-block:: jinja
+
+{% block form_label %}
+{% if not compound %}
+{% set label_attr = label_attr|merge({'for': id}) %}
+{% endif %}
+{% if required %}
+{% set label_attr = label_attr|merge({'class': (label_attr.class|default('') ~ ' required')|trim}) %}
+{% endif %}
+{% if label is empty %}
+{% set label = name|humanize %}
+{% endif %}
+<label{% for attrname, attrvalue in label_attr %} {{ attrname }}="{{ attrvalue }}"{% endfor %}>{{ label|trans({}, translation_domain) }}</label>
+{% endblock form_label %}
+
+This block makes use of several variables: ``compound``, ``label_attr``, ``required``,
+``label``, ``name`` and ``translation_domain``.
+These variables are made available by the form rendering system. But more
+importantly, these are the variables that you can override when calling ``form_label``
+(since in this example, you're rendering the label).
+
+The exact variables available to override depends on which part of the form
+you're rendering (e.g. label versus widget) and which field you're rendering
+(e.g. a ``choice`` widget has an extra ``expanded`` option). If you get comfortable
+with looking through `form_div_layout.html.twig`_, you'll always be able
+to see what options you have available.
+
+.. tip::
+
+Behind the scenes, these variables are made available to the ``FormView``
+object of your form when the form component calls ``buildView`` and ``buildViewBottomUp``
+on each "node" of your form tree. To see what "view" variables a particularly
+field has, find the source code for the form field (and its parent fields)
+and look at the above two functions.
+
+.. note::
+
+If you're rendering an entire form at once (or an entire embedded form),
+the ``variables`` argument will only be applied to the form itself and
+not its children. In other words, the following will **not** pass a "foo"
+class attribute to all of the child fields in the form:
+
+.. code-block:: jinja
+
+{# does **not** work - the variables are not recursive #}
+{{ form_widget(form, { 'attr': {'class': 'foo'} }) }}
+
+.. _`form_div_layout.html.twig`: https://.com/symfony/symfony/blob/2.1/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig