Reorganized the contents of the new output sections

Author: javiereguiluz

components/console/helpers/progressbar.rst

@@ -342,3 +342,43 @@ of the custom placeholders::
         $progressBar->advance();
         // 2/100 -- Importing invoices... (client-001/invoices.xml)
     }
+
+.. _console-multiple-progress-bars:
+
+Displaying Multiple Progress Bars
+---------------------------------
+
+.. versionadded:: 4.1
+    The feature to display multiple progress bars using output sections was
+    introduced in Symfony 4.1.
+
+When using :ref:`Console output sections <console-output-sections>` it's
+possible to display multiple progress bars at the same time and change their
+progress independently::
+
+    $section1 = $output->section();
+    $section2 = $output->section();
+
+    $progress1 = new ProgressBar($section1);
+    $progress2 = new ProgressBar($section2);
+
+    $progress1->start(100);
+    $progress2->start(100);
+
+    $i = 0;
+    while (++$i < 100) {
+        $progress1->advance();
+
+        if ($i % 2 === 0) {
+            $progress2->advance(4);
+        }
+
+        usleep(50000);
+    }
+
+After a couple of iterations, the output in the terminal will look like this:
+
+.. code-block:: text
+
+    34/100 [=========>------------------]  34%
+    68/100 [===================>--------]  68%

components/console/helpers/table.rst

@@ -324,3 +324,47 @@ This outputs:
 
 You can use the ``colspan`` and ``rowspan`` options at the same time which allows
 you to create any table layout you may wish.
+
+.. _console-modify-rendered-tables:
+
+Modifying Rendered Tables
+-------------------------
+
+.. versionadded:: 4.1
+    The feature to modify rendered tables was introduced in Symfony 4.1.
+
+The ``render()`` method requires passing the entire table contents. However,
+sometimes that information is not available beforehand because it's generated
+dynamically. In those cases, use the
+:method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method, which
+takes the same arguments as the ``addRow()`` method, to add rows at the bottom
+of an already rendered table.
+
+The only requirement to append rows is that the table must be rendered inside a
+:ref:`Console output section <console-output-sections>`::
+
+    use Symfony\Component\Console\Helper\Table;
+    // ...
+
+    class SomeCommand extends Command
+    {
+        public function execute(InputInterface $input, OutputInterface $output)
+        {
+            $section = $output->section();
+            $table = new Table($section);
+
+            $table->addRow(['Row 1']);
+            $table->render();
+
+            $table->addRow(['Row 2']);
+        }
+    }
+
+This will display the following table in the terminal:
+
+.. code-block:: terminal
+
+    +-------+
+    | Row 1 |
+    | Row 2 |
+    +-------+

console.rst

@@ -87,9 +87,13 @@ After configuring and registering the command, you can execute it in the termina
     $ php bin/console app:create-user
 
 As you might expect, this command will do nothing as you didn't write any logic
-yet. Add your own logic inside the ``execute()`` method, which has access to the
-input stream (e.g. options and arguments) and the output stream (to write
-messages to the console)::
+yet. Add your own logic inside the ``execute()`` method.
+
+Console Output
+--------------
+
+The ``execute()`` method has access to the output stream to write messages to
+the console::
 
     // ...
     protected function execute(InputInterface $input, OutputInterface $output)
@@ -128,6 +132,57 @@ Now, try executing the command:
     Whoa!
     You are about to create a user.
 
+.. _console-output-sections:
+
+Output Sections
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.1
+    Output sections were introduced in Symfony 4.1.
+
+The regular console output can be divided into multiple independent regions
+called "output sections". Create one or more of these sections when you need to
+clear and overwrite the output information.
+
+Sections are created with the
+:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method,
+which returns an instance of
+:class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput`::
+
+    class MyCommand extends Command
+    {
+        protected function execute(InputInterface $input, OutputInterface $output)
+        {
+            $section1 = $output->section();
+            $section2 = $output->section();
+            $section1->writeln('Hello');
+            $section2->writeln('World!');
+            // Output displays "Hello\nWorld!\n"
+
+            // overwrite() replaces all the existing section contents with the given content
+            $section1->overwrite('Goodbye');
+            // Output now displays "Goodbye\nWorld!\n"
+
+            // clear() deletes all the section contents...
+            $section2->clear();
+            // Output now displays "Goodbye\n"
+
+            // ...but you can also delete a given number of lines
+            // (this example deletes the last two lines of the section)
+            $section1->clear(2);
+            // Output is now completely empty!
+        }
+    }
+
+.. note::
+
+    A new line is appended automatically when displaying information in a section.
+
+Output sections let you manipulate the Console output in advanced ways, such as
+:ref:`displaying multiple progress bars <console-multiple-progress-bars>` which
+are updated independently and :ref:`appending rows to tables <console-modify-rendered-tables>`
+that have already been rendered.
+
 Console Input
 -------------