Merge branch '3.4' into 4.2

* 3.4:
  [Workflow] Update the article about dumping workflows
  Added a short guide to help creating the Symfony diagrams

Author: javiereguiluz

_images/sources/README.md

@@ -0,0 +1,58 @@
+How to Create Symfony Diagrams
+==============================
+
+Creating the Diagram
+--------------------
+
+* Use [Dia][1] as the diagramming application;
+* Use [PT Sans Narrow][2] as the only font in all diagrams (if possible, use
+  only the "normal" weight for all contents);
+* Use 36pt as the base font size;
+* Use 0.10 cm width for lines and shape borders;
+* Use the following color palette:
+  * Text, lines and shape borders: black (#000000)
+  * Shape backgrounds:
+    * Grays: dark (#4d4d4d), medium (#b3b3b3), light (#f2f2f2)
+    * Blue: #b2d4eb
+    * Red: #ecbec0
+    * Green: #b2dec7
+    * Orange: #fddfbb
+
+In case of doubt, check the existing diagrams or ask to the
+[Symfony Documentation Team][3].
+
+Saving and Exporting the Diagram
+--------------------------------
+
+* Save the original diagram in `*.dia` format in `_images/sources/<folder-name>`;
+* Export the diagram to SVG format and save it in `_images/<folder-name>`.
+
+Including the Diagram in the Symfony Docs
+-----------------------------------------
+
+Use the following snippet to embed the diagram in the docs:
+
+```
+.. raw:: html
+
+    <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"></object>
+```
+
+Reasoning
+---------
+
+* Dia was chosen because it's one of the few applications which are free, open
+  source and compatible with Linux, macOS and Windows.
+* Font, colors and line widths were chosen to be similar to the diagrams used
+  in the best tech books.
+
+Troubleshooting
+---------------
+
+* On some macOS systems, Dia cannot be executed as a regular application and
+  you must run the following console command instead:
+  `export DISPLAY=:0 && /Applications/Dia.app/Contents/Resources/bin/dia`
+
+[1]: http://dia-installer.de/
+[2]: https://fonts.google.com/specimen/PT+Sans+Narrow
+[3]: https://symfony.com/doc/current/contributing/code/core_team.html

reference/forms/types/options/checkbox_empty_data.rst.inc

@@ -5,4 +5,4 @@ empty_data
 
 This option determines what value the field will return when the ``placeholder``
 choice is selected. In the checkbox and the radio type, the value of ``empty_data``
-is overriden by the value returned by the data transformer (see :doc:`/form/data_transformers`).
+is overridden by the value returned by the data transformer (see :doc:`/form/data_transformers`).

reference/forms/types/options/data.rst.inc

@@ -19,6 +19,6 @@ an individual field, you can set it in the data option::
 .. caution::
 
     The ``data`` option *always* overrides the value taken from the domain data
-    (object) when rendering. This means the object value is also overriden when
+    (object) when rendering. This means the object value is also overridden when
     the form edits an already persisted object, causing it to lose its
     persisted value when the form is submitted.

workflow/dumping-workflows.rst

@@ -4,63 +4,55 @@
 How to Dump Workflows
 =====================
 
-To help you debug your workflows, you can dump a representation of your workflow
-or state machine with the use of a ``DumperInterface``. Symfony provides two
-different dumpers, both based on Dot (see below).
+To help you debug your workflows, you can generate a visual representation of
+them as SVG or PNG images. First, install any of these free and open source
+applications needed to generate the images:
 
-Use the ``GraphvizDumper`` or ``StateMachineGraphvizDumper`` to create DOT
-files, or use ``PlantUmlDumper`` for PlantUML files. Both types can be converted
-to PNG or SVG images.
+* `Graphviz`_, provides the ``dot`` command;
+* `PlantUML`_, provides the ``plantuml.jar`` file (which requires Java).
 
-Images of the workflow defined above::
-
-    // dump-graph-dot.php
-    $dumper = new GraphvizDumper();
-    echo $dumper->dump($definition);
-
-    // dump-graph-puml.php
-    $dumper = new PlantUmlDumper();
-    echo $dumper->dump($definition);
+If you are defining the workflow inside a Symfony application, run this command
+to dump it as an image:
 
 .. code-block:: terminal
 
-    # dump DOT file in PNG image:
-    $ php dump-graph-dot.php | dot -Tpng -o dot_graph.png
+    # using Graphviz's 'dot' and SVG images
+    $ php bin/console workflow:dump workflow-name | dot -Tsvg -o graph.svg
+
+    # using Graphviz's 'dot' and PNG images
+    $ php bin/console workflow:dump workflow-name | dot -Tpng -o graph.png
 
-    # dump DOT file in SVG image:
-    # $ php dump-graph-dot.php | dot -Tsvg -o dot_graph.svg
+    # using PlantUML's 'plantuml.jar'
+    $ php bin/console workflow:dump workflow_name --dump-format=puml | java -jar plantuml.jar -p  > graph.png
 
-    # dump PlantUML in PNG image:
-    $ php dump-graph-puml.php | java -jar plantuml.jar -p  > puml_graph.png
+    # highlight 'place1' and 'place2' in the dumped workflow
+    $ php bin/console workflow:dump workflow-name place1 place2 | dot -Tsvg -o graph.svg
 
-The DOT result will look like this:
+The DOT image will look like this:
 
 .. image:: /_images/components/workflow/blogpost.png
 
-The PlantUML result:
+The PlantUML image will look like this:
 
 .. image:: /_images/components/workflow/blogpost_puml.png
 
-Inside a Symfony application, you can dump the files with those commands using
-``workflow:dump`` command:
+If you are creating workflows outside of a Symfony application, use the
+``GraphvizDumper`` or ``StateMachineGraphvizDumper`` class to create the DOT
+files and ``PlantUmlDumper`` to create the PlantUML files::
 
-.. code-block:: terminal
-
-    $ php bin/console workflow:dump workflow_name | dot -Tpng -o workflow_name.png
-    $ php bin/console workflow:dump workflow_name | dot -Tsvg -o workflow_name.svg
-    $ php bin/console workflow:dump workflow_name --dump-format=puml | java -jar plantuml.jar -p  > workflow_name.png
-
-    # highlight 'place1' and 'place2' in the dumped workflow
-    $ php bin/console workflow:dump name place1 place2 | dot -Tsvg -o graph.svg
-
-.. note::
+    // Add this code to a PHP script; for example: dump-graph.php
+    $dumper = new GraphvizDumper();
+    echo $dumper->dump($definition);
 
-    The ``dot`` command is part of Graphviz. You can download it and read
-    more about it on `Graphviz.org`_.
+    # if you prefer PlantUML, use this code:
+    # $dumper = new PlantUmlDumper();
+    # echo $dumper->dump($definition);
 
-    The ``plantuml.jar`` command is part of PlantUML. You can download it and
-    read more about it on `PlantUML.com`_.
+.. code-block:: terminal
 
+    # replace 'dump-graph.php' by the name of your PHP script
+    $ php dump-graph.php | dot -Tsvg -o graph.svg
+    $ php dump-graph.php | java -jar plantuml.jar -p  > graph.png
 
-.. _Graphviz.org: http://www.graphviz.org
-.. _PlantUML.com: http://plantuml.com/
+.. _`Graphviz`: http://www.graphviz.org
+.. _`PlantUML`: http://plantuml.com/