Merge branch '2.3' into 2.4

weaverryan · weaverryan · commit a6724f46f277 · 2014-10-02T09:14:21.000-04:00
* 2.3:
  Added information about float choice lists
  tweaks to the contribution chapter
  Reverted removal, removed API links instead
  [2.3] Examples that points to the DataCollectorListener should be removed.

Conflicts:
	components/form/form_events.rst
diff --git a/components/form/form_events.rst b/components/form/form_events.rst
@@ -83,7 +83,7 @@ The ``FormEvents::PRE_SET_DATA`` event is dispatched at the beginning of the
 .. sidebar:: ``FormEvents::PRE_SET_DATA`` in the Form component
 
     The ``collection`` form type relies on the
-    :class:`Symfony\\Component\\Form\\Extension\\Core\\EventListener\\ResizeFormListener`
+    ``Symfony\Component\Form\Extension\Core\EventListener\ResizeFormListener``
     subscriber, listening to the ``FormEvents::PRE_SET_DATA`` event in order
     to reorder the form's fields depending on the data from the pre-populated
     object, by removing and adding all form rows.
@@ -113,7 +113,7 @@ the form.
     .. versionadded:: 2.4
         The data collector extension was introduced in Symfony 2.4.
 
-    The :class:`Symfony\\Component\\Form\\Extension\\DataCollector\\EventListener\\DataCollectorListener`
+    The ``Symfony\Component\Form\Extension\DataCollector\EventListener\DataCollectorListener``
     class is subscribed to listen to the ``FormEvents::POST_SET_DATA`` event
     in order to collect information about the forms from the denormalized
     model and view data.
@@ -155,10 +155,10 @@ It can be used to:
 
 .. sidebar:: ``FormEvents::PRE_SUBMIT`` in the Form component
 
-    The :class:`Symfony\\Component\\Form\\Extension\\Core\\EventListener\\TrimListener`
+    The ``Symfony\Component\Form\Extension\Core\EventListener\TrimListener``
     subscriber subscribes to the ``FormEvents::PRE_SUBMIT`` event in order to
     trim the request's data (for string values).
-    The :class:`Symfony\\Component\\Form\\Extension\\Csrf\\EventListener\\CsrfValidationListener`
+    The ``Symfony\Component\Form\Extension\Csrf\EventListener\CsrfValidationListener``
     subscriber subscribes to the ``FormEvents::PRE_SUBMIT`` event in order to
     validate the CSRF token.
 
@@ -189,7 +189,7 @@ It can be used to change data from the normalized representation of the data.
 
 .. sidebar:: ``FormEvents::SUBMIT`` in the Form component
 
-    The :class:`Symfony\\Component\\Form\\Extension\\Core\\EventListener\\ResizeFormListener`
+    The ``Symfony\Component\Form\Extension\Core\EventListener\ResizeFormListener``
     subscribes to the ``FormEvents::SUBMIT`` event in order to remove the
     fields that need to be removed whenever manipulating a collection of forms
     for which ``allow_delete`` has been enabled.
@@ -224,10 +224,10 @@ It can be used to fetch data after denormalization.
     .. versionadded:: 2.4
         The data collector extension was introduced in Symfony 2.4.
 
-    The :class:`Symfony\\Component\\Form\\Extension\\DataCollector\\EventListener\\DataCollectorListener`
+    The ``Symfony\Component\Form\Extension\DataCollector\EventListener\DataCollectorListener``
     subscribes to the ``FormEvents::POST_SUBMIT`` event in order to collect
     information about the forms.
-    The :class:`Symfony\\Component\\Form\\Extension\\Validator\\EventListener\\ValidationListener`
+    The ``Symfony\Component\Form\Extension\Validator\EventListener\ValidationListener``
     subscribes to the ``FormEvents::POST_SUBMIT`` event in order to
     automatically validate the denormalized object, and update the normalized
     as well as the view's representations.
diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
@@ -33,24 +33,15 @@ roles to the standard reST markup. Read more about the `Sphinx Markup Constructs
 Syntax Highlighting
 ~~~~~~~~~~~~~~~~~~~
 
-PHP is the default syntax highlight applied to all code blocks. You can change
-it with the ``code-block`` directive:
+PHP is the default syntax highlighter applied to all code blocks. You can
+change it with the ``code-block`` directive:
 
 .. code-block:: rst
 
     .. code-block:: yaml
 
         { foo: bar, bar: { foo: bar, bar: baz } }
 
-If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
-the name of the highlighted syntax:
-
-.. code-block:: rst
-
-    .. code-block:: html+php
-
-        <?php echo $this->foobar(); ?>
-
 .. note::
 
     Besides all of the major programming languages, the syntax highlighter
@@ -183,7 +174,7 @@ If you're documenting a brand new feature or a change that's been made in
 Symfony, you should precede your description of the change with a
 ``.. versionadded:: 2.X`` directive and a short description:
 
-.. code-block:: text
+.. code-block:: rst
 
     .. versionadded:: 2.3
         The ``askHiddenResponse`` method was introduced in Symfony 2.3.
@@ -193,7 +184,7 @@ Symfony, you should precede your description of the change with a
 If you're documenting a behavior change, it may be helpful to *briefly* describe
 how the behavior has changed.
 
-.. code-block:: text
+.. code-block:: rst
 
     .. versionadded:: 2.3
         The ``include()`` function is a new Twig feature that's available in
@@ -204,7 +195,7 @@ a new branch of the documentation is created from the ``master`` branch.
 At this point, all the ``versionadded`` tags for Symfony versions that have
 reached end-of-life will be removed. For example, if Symfony 2.5 were released
 today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded``
-tags would be removed from the new 2.5 branch.
+tags would be removed from the new ``2.5`` branch.
 
 Testing Documentation
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
@@ -3,10 +3,10 @@ Contributing to the Documentation
 
 One of the essential principles of the Symfony project is that **documentation is
 as important as code**. That's why a great amount of resources are dedicated to
-documenting new features and to keeping the rest of the documentation up to date.
+documenting new features and to keeping the rest of the documentation up-to-date.
 
-More than 800 developers all around the world have contributed to Symfony's
-documentation, and we are glad that you are considering joining this big family.
+More than 700 developers all around the world have contributed to Symfony's
+documentation and we are glad that you are considering joining this big family.
 This guide will explain everything you need to contribute to the Symfony
 documentation.
 
@@ -27,9 +27,9 @@ Before Your First Contribution
 Your First Documentation Contribution
 -------------------------------------
 
-In this section you'll learn how to contribute to the Symfony documentation for
+In this section, you'll learn how to contribute to the Symfony documentation for
 the first time. The next section will explain the shorter process you'll follow
-in the future for every contribution after your first.
+in the future for every contribution after your first one.
 
 Let's imagine that you want to improve the installation chapter of the Symfony
 book. In order to make your changes, follow these steps:
@@ -164,8 +164,12 @@ Now you can **sync your fork** by executing the following command:
 
     $ cd projects/symfony-docs/
     $ git fetch upstream
-    $ git checkout master
-    $ git merge upstream/master
+    $ git checkout 2.3
+    $ git merge upstream/2.3
+
+This command will update the ``2.3`` branch, which is the one you used to
+create the new branch for your changes. If have used another base branch,
+e.g. ``master``, replace the ``2.3`` with the appropriate branch name.
 
 Great! Now you can proceed by following the same steps explained in the previous
 section:
@@ -212,8 +216,8 @@ steps to contribute to the Symfony documentation, which you can use as a
     # sync your fork with the official Symfony repository
     $ cd projects/symfony-docs/
     $ git fetch upstream
-    $ git checkout master
-    $ git merge upstream/master
+    $ git checkout 2.3
+    $ git merge upstream/2.3
 
     # create a new branch from the oldest maintained version
     $ git checkout 2.3
@@ -262,10 +266,11 @@ Why Should I Use the Oldest Maintained Branch Instead of the Master Branch?
 
 Consistent with Symfony's source code, the documentation repository is split
 into multiple branches, corresponding to the different versions of Symfony itself.
-The master branch holds the documentation for the development branch of the code.
+The ``master`` branch holds the documentation for the development branch of
+the code.
 
 Unless you're documenting a feature that was introduced after Symfony 2.3,
-your changes should always be based on the 2.3 branch. Documentation managers
+your changes should always be based on the ``2.3`` branch. Documentation managers
 will use the necessary Git-magic to also apply your changes to all the active
 branches of the documentation.
 
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -93,6 +93,14 @@ is the item value and the array value is the item's label::
         'choices' => array('m' => 'Male', 'f' => 'Female')
     ));
 
+.. tip::
+
+    When the values to choose from are not integers or strings (but e.g. floats
+    or booleans), you should use the `choice_list`_ option instead. With this
+    option you are able to keep the original data format which is important
+    to ensure that the user input is validated properly and useless database
+    updates caused by a data type mismatch are avoided.
+
 choice_list
 ~~~~~~~~~~~
 
@@ -103,6 +111,17 @@ The ``choice_list`` option must be an instance of the ``ChoiceListInterface``.
 For more advanced cases, a custom class that implements the interface
 can be created to supply the choices.
 
+With this option you can also allow float values to be selected as data.
+
+.. code-block:: php
+
+    use Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceList;
+
+    // ...
+    $builder->add('status', 'choice', array(
+      'choice_list' => new ChoiceList(array(1, 0.5), array('Full', 'Half')
+    ));
+
 .. include:: /reference/forms/types/options/empty_value.rst.inc
 
 .. include:: /reference/forms/types/options/expanded.rst.inc
