[symfony#1999] Proofreading the new dialog and formatter console helpers

weaverryan · weaverryan · commit c9a2f325febb · 2012-12-26T13:24:53.000-05:00
diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst
@@ -11,14 +11,15 @@ 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.
+:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as first the
+argument, the question as the 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::
+the following to you command::
 
     // ...
     if (!$dialog->askConfirmation(
@@ -34,7 +35,7 @@ In this case, the user will be asked "Continue with this action", and will retur
 argument to ``askConfirmation`` is the default value to return if the user doesn't 
 enter any input.
 
-Asking the User for information
+Asking the User for Information
 -------------------------------
 
 You can also ask question with more than a simple yes/no answer. For instance,
@@ -47,16 +48,16 @@ if you want to know a bundle name, you can add this to your command::
         'AcmeDemoBundle'
     );
 
-The user will be asked "Please enter the name of the bundle". They can type
-some name which will be returned by the ``ask`` method. If they leave it empty
+The user will be asked "Please enter the name of the bundle". She can type
+some name which will be returned by the ``ask`` method. If she leaves it empty,
 the default value (``AcmeDemoBundle`` here) is returned.
 
-Validating the answer
+Validating the Answer
 ---------------------
 
-You can even validate the answer. For instance, in our last example we asked
+You can even validate the answer. For instance, in the last example you asked
 for the bundle name. Following the Symfony2 naming conventions, it should
-be suffixed with ``Bundle``. We can validate that by using the 
+be suffixed with ``Bundle``. You can validate that by using the 
 :method:`Symfony\\Component\\Console\\Helper\\DialogHelper::askAndValidate` 
 method::
 
@@ -87,11 +88,11 @@ 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 is displayed
-in the console, so it is a good practice to put some usefull information 
+in the console, so it is a good practice to put some useful 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
+If you reach this max number it will use the default value, which is given
 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.
+be able to proceed if her input is valid.
diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst
@@ -5,33 +5,41 @@ 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
+You can do more advanced things with this helper than you can in
 :ref:`components-console-coloring`.
 
-The Formatter Helper 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 which in most cases you want to write
-that data to the console with
-:method:`Symfony\\Component\\Console\\Output\\Output::writeln`.
+The methods return a string, which you'll usually render to the console by
+passing it to the
+:method:`OutputInterface::writeln<Symfony\\Component\\Console\\Output\\OutputInterface::writeln>` method.
 
-Print messages in a section
+Print Messages in a Section
 ---------------------------
 
-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.
+Symfony offers a defined style when printing a message that belongs to some
+"section". It prints the section in color and with brackets around it and the
+actual message to the right of this. Minus the color, it looks like this:
+
+.. code-block:: text
+
+    [SomeSection] Here is some message related to that section
 
 To reproduce this style, you can use the 
-:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`::
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`
+method::
 
-    $formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
+    $formattedLine = $formatter->formatSection(
+        'SomeSection',
+        'Here is some message related to that section'
+    );
     $output->writeln($formattedLine);
     
-Print messages in a block
+Print Messages in a Block
 -------------------------
 
 Sometimes you want to be able to print a whole block of text with a background
@@ -40,13 +48,18 @@ 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. Use the
 :method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
-togenerate a block output::
+to generate a block output::
 
     $errorMessages = array('Error!', 'Something went wrong');
     $formattedBlock = $formatter->formatBlock($errorMessages, 'error');
+    $output->writeln($formattedBlock);
     
 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).
+block will be formatted with more padding (one blank line above and below the
+messages and 2 spaces on the left and right).
+
+The exact "style" you use in the block is up to you. In this case, you're using
+the pre-defined ``error`` style, but there are other styles, or you can create
+your own. See :ref:`components-console-coloring`.
diff --git a/components/console/introduction.rst b/components/console/introduction.rst
@@ -275,8 +275,8 @@ Console Helpers
 The console component also contains a set of "helpers" - different small
 tools capable of helping you with different tasks:
 
-* :doc:`/component/console/helpers/dialoghelper`: interactively ask the user for information
-* :doc:`/component/console/helpers/formatterhelper`: customize the output colorization
+* :doc:`/components/console/helpers/dialoghelper`: interactively ask the user for information
+* :doc:`/components/console/helpers/formatterhelper`: customize the output colorization
 
 Testing Commands
 ----------------
