From 7f5a626ca21cde9d3ab6039f845f015d4684f0ec Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sat, 10 Nov 2012 18:27:00 +0100
Subject: [PATCH 1/7] Created introduction and toctrees

---
 components/console/helpers/index.rst   | 13 +++++++++++++
 components/console/helpers/map.rst.inc |  0
 components/console/index.rst           |  2 ++
 components/map.rst.inc                 |  1 +
 4 files changed, 16 insertions(+)
 create mode 100644 components/console/helpers/index.rst
 create mode 100644 components/console/helpers/map.rst.inc

diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst
new file mode 100644
index 00000000000..4ad4847c073
--- /dev/null
+++ b/components/console/helpers/index.rst
@@ -0,0 +1,13 @@
+.. index::
+    single: Console; Console Helpers
+
+Console Helpers
+===============
+
+.. toctree::
+    :maxdepth: 2
+
+The Console Components comes with some usefull helpers. These helpers contain
+function to ease some common tasks.
+
+.. include:: map.rst.inc
diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/components/console/index.rst b/components/console/index.rst
index b3e3cf95d97..4d0a12e4d70 100644
--- a/components/console/index.rst
+++ b/components/console/index.rst
@@ -7,3 +7,5 @@ Console
     introduction
     usage
     single_command_tool
+
+    helpers/index
diff --git a/components/map.rst.inc b/components/map.rst.inc
index 97cb03134c1..0529c6d4e16 100644
--- a/components/map.rst.inc
+++ b/components/map.rst.inc
@@ -14,6 +14,7 @@
   * :doc:`/components/console/introduction`
   * :doc:`/components/console/usage`
   * :doc:`/components/console/single_command_tool`
+  * :doc:`/components/console/helpers/index`
 
 * **CSS Selector**
 

From d162a5cd069763cbd62f63213727a32a1cbd0bfb Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sun, 11 Nov 2012 00:12:51 +0100
Subject: [PATCH 2/7] Created DialogHelper documentation

---
 components/console/helpers/dialoghelper.rst | 96 +++++++++++++++++++++
 components/console/helpers/index.rst        |  3 +
 components/console/helpers/map.rst.inc      |  1 +
 components/console/introduction.rst         | 34 +-------
 4 files changed, 101 insertions(+), 33 deletions(-)
 create mode 100644 components/console/helpers/dialoghelper.rst

diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst
new file mode 100644
index 00000000000..cb33038537b
--- /dev/null
+++ b/components/console/helpers/dialoghelper.rst
@@ -0,0 +1,96 @@
+.. index::
+    single: Console Helpers; Dialog Helper
+
+Dialog Helper
+=============
+
+The Dialog Helper provides functions to ask the user for more information.
+
+The DialogHelper is included in the default helper set, which you can get
+by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
+
+    $dialog = $this->getHelperSet()->get('dialog');
+
+All the methods inside the Dialog Helper have an 
+:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as first argument,
+the question as second argument and the default value as last argument.
+
+Asking the User for confirmation
+--------------------------------
+
+Suppose you want to confirm an action before actually executing it. Add 
+the following to your command::
+
+    // ...
+    if (!$dialog->askConfirmation(
+            $output,
+            '<question>Continue with this action?</question>',
+            false
+        )) {
+        return;
+    }
+
+In this case, the user will be asked "Continue with this action", and unless
+they answer with ``y``, the task will stop running. The third argument to
+``askConfirmation`` is the default value to return if the user doesn't enter
+any input.
+
+Asking the User for information
+-------------------------------
+
+You can also ask question with more than a simple yes/no answer. For instance,
+you want to know a bundle name, you can add this to your command::
+
+    // ...
+    $bundle = $dialog->ask(
+        $output,
+        'Please enter the name of the bundle',
+        'AcmeDemoBundle'
+    );
+
+The user will be asked "Please enter the name of the bundle". They can type
+some name or if they leave it empty the default value (``AcmeDemoBundle`` here)
+is used. This value will be returned.
+
+Validating the answer
+---------------------
+
+You can even validate the answer. For instance, in our last example we asked
+for the bundle name. Following the Symfony2 naming conventions, it should
+be suffixed with ``Bundle``. We can validate that by using the 
+:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::askAndValidate` 
+method::
+
+    // ...
+    $bundle = $dialog->askAndValidate(
+        $output,
+        'Please enter the name of the bundle',
+        function ($answer) {
+            if ('Bundle' !== substr($answer, -6)) {
+                throw new \RunTimeException(
+                    'The name of the bundle should be suffixed with \'Bundle\''
+                );
+            }
+        },
+        false,
+        'AcmeDemoBundle'
+    );
+
+This methods has 2 new arguments, the full signature is::
+
+    askAndValidate(
+        OutputInterface $output, 
+        string|array $question, 
+        callback $validator, 
+        integer $attempts = false, 
+        string $default = null
+    )
+
+The ``$validator`` is a callback which handles the validation. It should
+throw an exception if there is something wrong. The exception message displayed
+in the console, so it is a good practice to put some usefull information 
+in it.
+
+You can set the max number of times to ask in the ``$attempts`` argument.
+If we reach this max number it will use the default value, which is given
+in the last argument. This is ``false`` by default, which means it is infinite.
diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst
index 4ad4847c073..0526b75d819 100644
--- a/components/console/helpers/index.rst
+++ b/components/console/helpers/index.rst
@@ -7,6 +7,9 @@ Console Helpers
 .. toctree::
     :maxdepth: 2
 
+    dialoghelper
+
+
 The Console Components comes with some usefull helpers. These helpers contain
 function to ease some common tasks.
 
diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc
index e69de29bb2d..2e8a855ad81 100644
--- a/components/console/helpers/map.rst.inc
+++ b/components/console/helpers/map.rst.inc
@@ -0,0 +1 @@
+* :doc:`/components/console/helpers/dialoghelper`
diff --git a/components/console/introduction.rst b/components/console/introduction.rst
index a7412879a60..994a5e263a0 100755
--- a/components/console/introduction.rst
+++ b/components/console/introduction.rst
@@ -255,38 +255,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
             1
         );
 
-Asking the User for Information
--------------------------------
-
-When creating commands, you have the ability to collect more information
-from the user by asking him/her questions. For example, suppose you want
-to confirm an action before actually executing it. Add the following to your
-command::
-
-    $dialog = $this->getHelperSet()->get('dialog');
-    if (!$dialog->askConfirmation(
-            $output,
-            '<question>Continue with this action?</question>',
-            false
-        )) {
-        return;
-    }
-
-In this case, the user will be asked "Continue with this action", and unless
-they answer with ``y``, the task will stop running. The third argument to
-``askConfirmation`` is the default value to return if the user doesn't enter
-any input.
-
-You can also ask questions with more than a simple yes/no answer. For example,
-if you needed to know the name of something, you might do the following::
-
-    $dialog = $this->getHelperSet()->get('dialog');
-    $name = $dialog->ask(
-        $output,
-        'Please enter the name of the widget',
-        'foo'
-    );
-
 Testing Commands
 ----------------
 
@@ -407,4 +375,4 @@ Learn More!
 * :doc:`/components/console/usage`
 * :doc:`/components/console/single_command_tool`
 
-.. _Packagist: https://packagist.org/packages/symfony/console
\ No newline at end of file
+.. _Packagist: https://packagist.org/packages/symfony/console

From bf9495279cf05523d3c7b23a3077d06ef56f85bc Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Mon, 12 Nov 2012 14:02:13 +0100
Subject: [PATCH 3/7] [WIP] FormatterHelper docs

---
 .../console/helpers/formatterhelper.rst       | 25 +++++++++++++++++++
 components/console/introduction.rst           |  2 ++
 2 files changed, 27 insertions(+)
 create mode 100644 components/console/helpers/formatterhelper.rst

diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst
new file mode 100644
index 00000000000..104d726ab68
--- /dev/null
+++ b/components/console/helpers/formatterhelper.rst
@@ -0,0 +1,25 @@
+.. index::
+    single: Console Helpers; Formatter Helper
+
+Formatter Helper
+================
+
+The Formatter helpers provides functions to format the output with colors.
+You can do more advanced things with this helper than the things in
+:ref:`components-console-coloring`.
+
+The FormatterHelper is included in the default helper set, which you can
+get by calling
+:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
+
+    $formatter = $this->getHelperSet()->get('formatter');
+
+The methods return a string with the data for the console, you should decide
+what you are going to do with that data. In most cases you want to write
+that data to the console with
+:method:`Symfony\\Component\\Console\\Output\\Output::writeln`.
+
+Print messages in a section
+---------------------------
+
+Assume you want to print
diff --git a/components/console/introduction.rst b/components/console/introduction.rst
index 994a5e263a0..d614c11f383 100755
--- a/components/console/introduction.rst
+++ b/components/console/introduction.rst
@@ -108,6 +108,8 @@ This prints::
 
     HELLO FABIEN
 
+.. _components-console-coloring:
+
 Coloring the Output
 ~~~~~~~~~~~~~~~~~~~
 

From 4de636102bc04c9259d3cd9438c3b132817381ca Mon Sep 17 00:00:00 2001
From: Sebastian Goettschkes <sebastian.goettschkes@googlemail.com>
Date: Mon, 3 Dec 2012 23:29:21 +0100
Subject: [PATCH 4/7] Making a few changes to the existing description and
 adding docs for the Formatter Helper

---
 components/console/helpers/dialoghelper.rst   | 25 ++++++++-------
 .../console/helpers/formatterhelper.rst       | 32 ++++++++++++++++---
 components/console/helpers/index.rst          |  1 -
 3 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst
index cb33038537b..647461f00d6 100644
--- a/components/console/helpers/dialoghelper.rst
+++ b/components/console/helpers/dialoghelper.rst
@@ -4,9 +4,8 @@
 Dialog Helper
 =============
 
-The Dialog Helper provides functions to ask the user for more information.
-
-The DialogHelper is included in the default helper set, which you can get
+The Dialog Helper provides functions to ask the user for more information. 
+It is included in the default helper set, which you can get
 by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
 
     $dialog = $this->getHelperSet()->get('dialog');
@@ -30,16 +29,16 @@ the following to your command::
         return;
     }
 
-In this case, the user will be asked "Continue with this action", and unless
-they answer with ``y``, the task will stop running. The third argument to
-``askConfirmation`` is the default value to return if the user doesn't enter
-any input.
+In this case, the user will be asked "Continue with this action", and will return
+``true`` if the user answers with ``y`` or false in any other case. The third 
+argument to ``askConfirmation`` is the default value to return if the user doesn't 
+enter any input.
 
 Asking the User for information
 -------------------------------
 
 You can also ask question with more than a simple yes/no answer. For instance,
-you want to know a bundle name, you can add this to your command::
+if you want to know a bundle name, you can add this to your command::
 
     // ...
     $bundle = $dialog->ask(
@@ -49,8 +48,8 @@ you want to know a bundle name, you can add this to your command::
     );
 
 The user will be asked "Please enter the name of the bundle". They can type
-some name or if they leave it empty the default value (``AcmeDemoBundle`` here)
-is used. This value will be returned.
+some name which will be returned by the ``ask`` method. If they leave it empty
+the default value (``AcmeDemoBundle`` here) is returned.
 
 Validating the answer
 ---------------------
@@ -87,10 +86,12 @@ This methods has 2 new arguments, the full signature is::
     )
 
 The ``$validator`` is a callback which handles the validation. It should
-throw an exception if there is something wrong. The exception message displayed
+throw an exception if there is something wrong. The exception message is displayed
 in the console, so it is a good practice to put some usefull information 
 in it.
 
 You can set the max number of times to ask in the ``$attempts`` argument.
 If we reach this max number it will use the default value, which is given
-in the last argument. This is ``false`` by default, which means it is infinite.
+in the last argument. Using ``false`` means the amount of attempts is infinite.
+The user will be asked as long as he provides an invalid answer and will only
+be able to proceed if his input is valid.
\ No newline at end of file
diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst
index 104d726ab68..5cb7aa6b3f1 100644
--- a/components/console/helpers/formatterhelper.rst
+++ b/components/console/helpers/formatterhelper.rst
@@ -8,18 +8,42 @@ The Formatter helpers provides functions to format the output with colors.
 You can do more advanced things with this helper than the things in
 :ref:`components-console-coloring`.
 
-The FormatterHelper is included in the default helper set, which you can
+The Formatter Helper is included in the default helper set, which you can
 get by calling
 :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
 
     $formatter = $this->getHelperSet()->get('formatter');
 
-The methods return a string with the data for the console, you should decide
-what you are going to do with that data. In most cases you want to write
+The methods return a string which in most cases you want to write
 that data to the console with
 :method:`Symfony\\Component\\Console\\Output\\Output::writeln`.
 
 Print messages in a section
 ---------------------------
 
-Assume you want to print
+Symfony uses a defined style when printing to the command line.
+It prints the section in color and with brackets around and the
+actual message behind this section indication.
+
+To reproduce this style, you can use the `` formatSection`` method like this::
+
+    $formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
+    $output->writeln($formattedLine);
+    
+Print messages in a block
+-------------------------
+
+Sometimes you want to be able to print a whole block of text with a background
+color. Symfony uses this when printing error messages.
+
+If you print your error message on more than one line manually, you will 
+notice that the background is only as long as each individual line. You
+can use the `formatBlock` method to create a real block output::
+
+    $errorMessages = array('Error!', 'Something went wrong');
+    $formattedBlock = $formatter->formatBlock($errorMessages, 'error');
+    
+As you can see, passing an array of messages to the `formatBlock` method creates
+the desired output. If you pass `true` as third parameter, the block will be 
+formatted with more padding (one blank line above and below the messages and 2 
+spaces on the left and right).
\ No newline at end of file
diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst
index 0526b75d819..84e59745bfb 100644
--- a/components/console/helpers/index.rst
+++ b/components/console/helpers/index.rst
@@ -9,7 +9,6 @@ Console Helpers
 
     dialoghelper
 
-
 The Console Components comes with some usefull helpers. These helpers contain
 function to ease some common tasks.
 

From 1b2245f8d93ce5a9a011f8e81a5f67ebe11403f4 Mon Sep 17 00:00:00 2001
From: Sebastian Goettschkes <sebastian.goettschkes@googlemail.com>
Date: Tue, 4 Dec 2012 10:44:13 +0100
Subject: [PATCH 5/7] Adding the formatterhelper.rst to index and map

---
 components/console/helpers/index.rst   | 1 +
 components/console/helpers/map.rst.inc | 1 +
 2 files changed, 2 insertions(+)

diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst
index 84e59745bfb..c8ec54e691f 100644
--- a/components/console/helpers/index.rst
+++ b/components/console/helpers/index.rst
@@ -8,6 +8,7 @@ Console Helpers
     :maxdepth: 2
 
     dialoghelper
+    formatterhelper
 
 The Console Components comes with some usefull helpers. These helpers contain
 function to ease some common tasks.
diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc
index 2e8a855ad81..d324d8c2aeb 100644
--- a/components/console/helpers/map.rst.inc
+++ b/components/console/helpers/map.rst.inc
@@ -1 +1,2 @@
 * :doc:`/components/console/helpers/dialoghelper`
+* :doc:`/components/console/helpers/formatterhelper`

From 448d0511126b34232bee5ae4fcc5ab7ae06c1e47 Mon Sep 17 00:00:00 2001
From: Sebastian Goettschkes <sebastian.goettschkes@googlemail.com>
Date: Tue, 4 Dec 2012 10:44:42 +0100
Subject: [PATCH 6/7] Changing a few wordings as well as code references to
 methods

---
 components/console/helpers/formatterhelper.rst | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst
index 5cb7aa6b3f1..a52debce80f 100644
--- a/components/console/helpers/formatterhelper.rst
+++ b/components/console/helpers/formatterhelper.rst
@@ -25,7 +25,8 @@ Symfony uses a defined style when printing to the command line.
 It prints the section in color and with brackets around and the
 actual message behind this section indication.
 
-To reproduce this style, you can use the `` formatSection`` method like this::
+To reproduce this style, you can use the 
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`::
 
     $formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
     $output->writeln($formattedLine);
@@ -37,13 +38,15 @@ Sometimes you want to be able to print a whole block of text with a background
 color. Symfony uses this when printing error messages.
 
 If you print your error message on more than one line manually, you will 
-notice that the background is only as long as each individual line. You
-can use the `formatBlock` method to create a real block output::
+notice that the background is only as long as each individual line. Use the
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
+togenerate a block output::
 
     $errorMessages = array('Error!', 'Something went wrong');
     $formattedBlock = $formatter->formatBlock($errorMessages, 'error');
     
-As you can see, passing an array of messages to the `formatBlock` method creates
-the desired output. If you pass `true` as third parameter, the block will be 
-formatted with more padding (one blank line above and below the messages and 2 
-spaces on the left and right).
\ No newline at end of file
+As you can see, passing an array of messages to the 
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
+method creates the desired output. If you pass ``true`` as third parameter, the 
+block will be  formatted with more padding (one blank line above and below the
+messages and 2 spaces on the left and right).
\ No newline at end of file

From b85a526d92906b88f4bc3b174acd9142fdd06562 Mon Sep 17 00:00:00 2001
From: Sebastian Goettschkes <sebastian.goettschkes@googlemail.com>
Date: Wed, 5 Dec 2012 10:20:44 +0100
Subject: [PATCH 7/7] Fixing format issues mentioned by WouterJ

---
 components/console/helpers/index.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst
index c8ec54e691f..c11b6e1a994 100644
--- a/components/console/helpers/index.rst
+++ b/components/console/helpers/index.rst
@@ -1,11 +1,11 @@
 .. index::
     single: Console; Console Helpers
 
-Console Helpers
-===============
+The Console Helpers
+===================
 
 .. toctree::
-    :maxdepth: 2
+    :hidden:
 
     dialoghelper
     formatterhelper