From 4daf2c0b565b82bc0b0db83138845ba4112bf96a Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sat, 3 Jan 2015 14:42:01 +0100
Subject: [PATCH 1/6] Added addUsage() to specify usage patterns

---
 .../Component/Console/Command/Command.php     | 25 +++++++++++++++++++
 .../Console/Descriptor/TextDescriptor.php     |  6 ++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/src/Symfony/Component/Console/Command/Command.php b/src/Symfony/Component/Console/Command/Command.php
index b70692fc6ab09..a9011c7984619 100644
--- a/src/Symfony/Component/Console/Command/Command.php
+++ b/src/Symfony/Component/Console/Command/Command.php
@@ -43,6 +43,7 @@ class Command
     private $applicationDefinitionMergedWithArgs = false;
     private $code;
     private $synopsis;
+    private $usages = array();
     private $helperSet;
 
     /**
@@ -584,6 +585,30 @@ public function getSynopsis()
         return $this->synopsis;
     }
 
+    /**
+     * Add a command usage example.
+     *
+     * @param string $usage The usage, it'll be prefixed with the command name
+     */
+    public function addUsage($usage)
+    {
+        if (0 !== strpos($usage, $this->name)) {
+            $usage = sprintf('%s %s', $this->name, $usage);
+        }
+
+        $this->usages[] = $usage;
+    }
+
+    /**
+     * Returns alternative usages of the command.
+     *
+     * @return array
+     */
+    public function getUsages()
+    {
+        return $this->usages;
+    }
+
     /**
      * Gets a helper instance by name.
      *
diff --git a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
index 0b3dd5a41df22..0109e95077844 100644
--- a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
@@ -120,7 +120,11 @@ protected function describeCommand(Command $command, array $options = array())
 
         $this->writeText('<comment>Usage:</comment>', $options);
         $this->writeText("\n");
-        $this->writeText(' '.$command->getSynopsis(), $options);
+        $this->writeText('  '.$command->getSynopsis(), $options);
+        foreach ($command->getUsages() as $usage) {
+            $this->writeText("\n");
+            $this->writeText('  '.$usage, $options);
+        }
         $this->writeText("\n");
 
         if (count($command->getAliases()) > 0) {

From 43c1c85c51422c517be457b2b1cf2f826d5c4f7c Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sat, 3 Jan 2015 14:42:12 +0100
Subject: [PATCH 2/6] Made output docopt compatible

---
 .../Component/Console/Command/Command.php     |  17 ++-
 .../Console/Descriptor/JsonDescriptor.php     |   2 +-
 .../Console/Descriptor/MarkdownDescriptor.php |   3 +
 .../Console/Descriptor/TextDescriptor.php     | 131 +++++++++++-------
 .../Console/Descriptor/XmlDescriptor.php      |   4 +
 .../Console/Input/InputDefinition.php         |  40 +++++-
 .../Console/Tests/Command/CommandTest.php     |   4 +-
 .../Console/Tests/Command/HelpCommandTest.php |  22 +--
 .../Console/Tests/Command/ListCommandTest.php |   2 +-
 .../Descriptor/AbstractDescriptorTest.php     |   2 +-
 .../Tests/Descriptor/JsonDescriptorTest.php   |   8 ++
 .../Console/Tests/Fixtures/application_1.json |   2 +-
 .../Console/Tests/Fixtures/application_1.md   |   4 +-
 .../Console/Tests/Fixtures/application_1.txt  |  20 +--
 .../Console/Tests/Fixtures/application_1.xml  |   4 +-
 .../Console/Tests/Fixtures/application_2.json |   2 +-
 .../Console/Tests/Fixtures/application_2.md   |   6 +-
 .../Console/Tests/Fixtures/application_2.txt  |  30 ++--
 .../Console/Tests/Fixtures/application_2.xml  |   6 +-
 .../Tests/Fixtures/application_astext1.txt    |  26 ++--
 .../Tests/Fixtures/application_astext2.txt    |  18 +--
 .../Tests/Fixtures/application_asxml1.txt     |   4 +-
 .../Fixtures/application_renderexception2.txt |   2 +-
 .../Tests/Fixtures/application_run1.txt       |  20 +--
 .../Tests/Fixtures/application_run2.txt       |  26 ++--
 .../Tests/Fixtures/application_run3.txt       |  10 +-
 .../Console/Tests/Fixtures/command_1.json     |   2 +-
 .../Console/Tests/Fixtures/command_1.txt      |   2 +-
 .../Console/Tests/Fixtures/command_2.json     |   2 +-
 .../Console/Tests/Fixtures/command_2.md       |   2 +-
 .../Console/Tests/Fixtures/command_2.txt      |   6 +-
 .../Console/Tests/Fixtures/command_2.xml      |   2 +-
 .../Console/Tests/Fixtures/command_astext.txt |  19 +--
 .../Tests/Fixtures/definition_astext.txt      |  16 +--
 .../Tests/Fixtures/input_argument_1.txt       |   2 +-
 .../Tests/Fixtures/input_argument_2.txt       |   2 +-
 .../Tests/Fixtures/input_argument_3.txt       |   2 +-
 .../Tests/Fixtures/input_definition_2.txt     |   2 +-
 .../Tests/Fixtures/input_definition_3.txt     |   2 +-
 .../Tests/Fixtures/input_definition_4.txt     |   4 +-
 .../Console/Tests/Fixtures/input_option_1.txt |   2 +-
 .../Console/Tests/Fixtures/input_option_2.txt |   2 +-
 .../Console/Tests/Fixtures/input_option_3.txt |   2 +-
 .../Console/Tests/Fixtures/input_option_4.txt |   2 +-
 .../Tests/Input/InputDefinitionTest.php       |  49 ++++---
 45 files changed, 316 insertions(+), 221 deletions(-)

diff --git a/src/Symfony/Component/Console/Command/Command.php b/src/Symfony/Component/Console/Command/Command.php
index a9011c7984619..1c1f27c5c66ab 100644
--- a/src/Symfony/Component/Console/Command/Command.php
+++ b/src/Symfony/Component/Console/Command/Command.php
@@ -42,7 +42,7 @@ class Command
     private $applicationDefinitionMerged = false;
     private $applicationDefinitionMergedWithArgs = false;
     private $code;
-    private $synopsis;
+    private $synopsis = array();
     private $usages = array();
     private $helperSet;
 
@@ -216,7 +216,8 @@ protected function initialize(InputInterface $input, OutputInterface $output)
     public function run(InputInterface $input, OutputInterface $output)
     {
         // force the creation of the synopsis before the merge with the app definition
-        $this->getSynopsis();
+        $this->getSynopsis(true);
+        $this->getSynopsis(false);
 
         // add the application arguments and options
         $this->mergeApplicationDefinition();
@@ -573,16 +574,20 @@ public function getAliases()
 
     /**
      * Returns the synopsis for the command.
+     * 
+     * @param bool $short Whether to show the short version of the synopsis (with options folded) or not
      *
      * @return string The synopsis
      */
-    public function getSynopsis()
+    public function getSynopsis($short = false)
     {
-        if (null === $this->synopsis) {
-            $this->synopsis = trim(sprintf('%s %s', $this->name, $this->definition->getSynopsis()));
+        $key = $short ? 'short' : 'long';
+        
+        if (!isset($this->synopsis[$key])) {
+            $this->synopsis[$key] = trim(sprintf('%s %s', $this->name, $this->definition->getSynopsis($short)));
         }
 
-        return $this->synopsis;
+        return $this->synopsis[$key];
     }
 
     /**
diff --git a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
index 13785a40fe615..04d98a99f36c2 100644
--- a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
@@ -157,7 +157,7 @@ private function getCommandData(Command $command)
 
         return array(
             'name' => $command->getName(),
-            'usage' => $command->getSynopsis(),
+            'usage' => array_merge(array($command->getSynopsis()), $command->getUsages()),
             'description' => $command->getDescription(),
             'help' => $command->getProcessedHelp(),
             'aliases' => $command->getAliases(),
diff --git a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
index 78d48b9508be5..b29c646129cbb 100644
--- a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
@@ -97,6 +97,9 @@ protected function describeCommand(Command $command, array $options = array())
             .str_repeat('-', strlen($command->getName()))."\n\n"
             .'* Description: '.($command->getDescription() ?: '<none>')."\n"
             .'* Usage: `'.$command->getSynopsis().'`'."\n"
+            .array_reduce($command->getUsages(), function ($carry, $usage) {
+                return $carry .= '         `'.$usage.'`'."\n";
+            })
             .'* Aliases: '.(count($command->getAliases()) ? '`'.implode('`, `', $command->getAliases()).'`' : '<none>')
         );
 
diff --git a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
index 0109e95077844..8a60a90cfd31a 100644
--- a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
@@ -32,16 +32,18 @@ class TextDescriptor extends Descriptor
     protected function describeInputArgument(InputArgument $argument, array $options = array())
     {
         if (null !== $argument->getDefault() && (!is_array($argument->getDefault()) || count($argument->getDefault()))) {
-            $default = sprintf('<comment> (default: %s)</comment>', $this->formatDefaultValue($argument->getDefault()));
+            $default = sprintf('<comment> [default: %s]</comment>', $this->formatDefaultValue($argument->getDefault()));
         } else {
             $default = '';
         }
 
-        $nameWidth = isset($options['name_width']) ? $options['name_width'] : strlen($argument->getName());
+        $totalWidth = isset($options['total_width']) ? $options['total_width'] : strlen($argument->getName());
+        $spacingWidth = $totalWidth - strlen($argument->getName()) + 2;
 
-        $this->writeText(sprintf(" <info>%-${nameWidth}s</info> %s%s",
+        $this->writeText(sprintf("  <info>%s</info>%s%s%s",
             $argument->getName(),
-            str_replace("\n", "\n".str_repeat(' ', $nameWidth + 2), $argument->getDescription()),
+            str_repeat(' ', $spacingWidth),
+            str_replace("\n", "\n".str_repeat(' ', $totalWidth + 4), $argument->getDescription()),
             $default
         ), $options);
     }
@@ -52,18 +54,32 @@ protected function describeInputArgument(InputArgument $argument, array $options
     protected function describeInputOption(InputOption $option, array $options = array())
     {
         if ($option->acceptValue() && null !== $option->getDefault() && (!is_array($option->getDefault()) || count($option->getDefault()))) {
-            $default = sprintf('<comment> (default: %s)</comment>', $this->formatDefaultValue($option->getDefault()));
+            $default = sprintf('<comment> [default: %s]</comment>', $this->formatDefaultValue($option->getDefault()));
         } else {
             $default = '';
         }
 
-        $nameWidth = isset($options['name_width']) ? $options['name_width'] : strlen($option->getName());
-        $nameWithShortcutWidth = $nameWidth - strlen($option->getName()) - 2;
+        $value = '';
+        if ($option->acceptValue()) {
+            $value = '='.strtoupper($option->getName());
 
-        $this->writeText(sprintf(" <info>%s</info> %-${nameWithShortcutWidth}s%s%s%s",
-            '--'.$option->getName(),
-            $option->getShortcut() ? sprintf('(-%s) ', $option->getShortcut()) : '',
-            str_replace("\n", "\n".str_repeat(' ', $nameWidth + 2), $option->getDescription()),
+            if ($option->isValueOptional()) {
+                $value = '['.$value.']';
+            }
+        }
+
+        $totalWidth = isset($options['total_width']) ? $options['total_width'] : $this->calculateTotalWidthForOptions(array($option));
+        $synopsis = sprintf('%s%s',
+            $option->getShortcut() ? sprintf('-%s, ', $option->getShortcut()) : '    ',
+            sprintf('--%s%s', $option->getName(), $value)
+        );
+
+        $spacingWidth = $totalWidth - strlen($synopsis) + 2;
+
+        $this->writeText(sprintf("  <info>%s</info>%s%s%s%s",
+            $synopsis,
+            str_repeat(' ', $spacingWidth),
+            str_replace("\n", "\n".str_repeat(' ', $totalWidth + 4), $option->getDescription()),
             $default,
             $option->isArray() ? '<comment> (multiple values allowed)</comment>' : ''
         ), $options);
@@ -74,24 +90,16 @@ protected function describeInputOption(InputOption $option, array $options = arr
      */
     protected function describeInputDefinition(InputDefinition $definition, array $options = array())
     {
-        $nameWidth = 0;
-        foreach ($definition->getOptions() as $option) {
-            $nameLength = strlen($option->getName()) + 2;
-            if ($option->getShortcut()) {
-                $nameLength += strlen($option->getShortcut()) + 3;
-            }
-            $nameWidth = max($nameWidth, $nameLength);
-        }
+        $totalWidth = $this->calculateTotalWidthForOptions($definition->getOptions());
         foreach ($definition->getArguments() as $argument) {
-            $nameWidth = max($nameWidth, strlen($argument->getName()));
+            $totalWidth = max($totalWidth, strlen($argument->getName()));
         }
-        ++$nameWidth;
 
         if ($definition->getArguments()) {
             $this->writeText('<comment>Arguments:</comment>', $options);
             $this->writeText("\n");
             foreach ($definition->getArguments() as $argument) {
-                $this->describeInputArgument($argument, array_merge($options, array('name_width' => $nameWidth)));
+                $this->describeInputArgument($argument, array_merge($options, array('total_width' => $totalWidth)));
                 $this->writeText("\n");
             }
         }
@@ -101,11 +109,20 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
         }
 
         if ($definition->getOptions()) {
+            $laterOptions = array();
+            
             $this->writeText('<comment>Options:</comment>', $options);
-            $this->writeText("\n");
             foreach ($definition->getOptions() as $option) {
-                $this->describeInputOption($option, array_merge($options, array('name_width' => $nameWidth)));
+                if (strlen($option->getShortcut()) > 1) {
+                    $laterOptions[] = $option;
+                    continue;
+                }
                 $this->writeText("\n");
+                $this->describeInputOption($option, array_merge($options, array('total_width' => $totalWidth)));
+            }
+            foreach ($laterOptions as $option) {
+                $this->writeText("\n");
+                $this->describeInputOption($option, array_merge($options, array('total_width' => $totalWidth)));
             }
         }
     }
@@ -115,12 +132,13 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
      */
     protected function describeCommand(Command $command, array $options = array())
     {
-        $command->getSynopsis();
+        $command->getSynopsis(true);
+        $command->getSynopsis(false);
         $command->mergeApplicationDefinition(false);
 
         $this->writeText('<comment>Usage:</comment>', $options);
         $this->writeText("\n");
-        $this->writeText('  '.$command->getSynopsis(), $options);
+        $this->writeText('  '.$command->getSynopsis(true), $options);
         foreach ($command->getUsages() as $usage) {
             $this->writeText("\n");
             $this->writeText('  '.$usage, $options);
@@ -130,16 +148,18 @@ protected function describeCommand(Command $command, array $options = array())
         if (count($command->getAliases()) > 0) {
             $this->writeText("\n");
             $this->writeText('<comment>Aliases:</comment> <info>'.implode(', ', $command->getAliases()).'</info>', $options);
+            $this->writeText("\n");
         }
 
-        if ($definition = $command->getNativeDefinition()) {
+        $definition = $command->getNativeDefinition();
+        if ($definition->getOptions() || $definition->getArguments()) {
             $this->writeText("\n");
             $this->describeInputDefinition($definition, $options);
+            $this->writeText("\n");
         }
 
-        $this->writeText("\n");
-
         if ($help = $command->getProcessedHelp()) {
+            $this->writeText("\n");
             $this->writeText('<comment>Help:</comment>', $options);
             $this->writeText("\n");
             $this->writeText(' '.str_replace("\n", "\n ", $help), $options);
@@ -168,27 +188,12 @@ protected function describeApplication(Application $application, array $options
             }
 
             $this->writeText("<comment>Usage:</comment>\n", $options);
-            $this->writeText(" command [options] [arguments]\n\n", $options);
-            $this->writeText('<comment>Options:</comment>', $options);
-
-            $inputOptions = $application->getDefinition()->getOptions();
+            $this->writeText("  command [options] [arguments]\n\n", $options);
+            
+            $this->describeInputDefinition(new InputDefinition($application->getDefinition()->getOptions()), $options);
 
-            $width = 0;
-            foreach ($inputOptions as $option) {
-                $nameLength = strlen($option->getName()) + 2;
-                if ($option->getShortcut()) {
-                    $nameLength += strlen($option->getShortcut()) + 3;
-                }
-                $width = max($width, $nameLength);
-            }
-            ++$width;
-
-            foreach ($inputOptions as $option) {
-                $this->writeText("\n", $options);
-                $this->describeInputOption($option, array_merge($options, array('name_width' => $width)));
-            }
-
-            $this->writeText("\n\n", $options);
+            $this->writeText("\n");
+            $this->writeText("\n");
 
             $width = $this->getColumnWidth($description->getCommands());
 
@@ -202,12 +207,13 @@ protected function describeApplication(Application $application, array $options
             foreach ($description->getNamespaces() as $namespace) {
                 if (!$describedNamespace && ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
                     $this->writeText("\n");
-                    $this->writeText('<comment>'.$namespace['id'].'</comment>', $options);
+                    $this->writeText(' <comment>'.$namespace['id'].'</comment>', $options);
                 }
 
                 foreach ($namespace['commands'] as $name) {
                     $this->writeText("\n");
-                    $this->writeText(sprintf(" <info>%-${width}s</info> %s", $name, $description->getCommand($name)->getDescription()), $options);
+                    $spacingWidth = $width - strlen($name);
+                    $this->writeText(sprintf("  <info>%s</info>%s%s", $name, str_repeat(' ', $spacingWidth), $description->getCommand($name)->getDescription()), $options);
                 }
             }
 
@@ -256,4 +262,27 @@ private function getColumnWidth(array $commands)
 
         return $width + 2;
     }
+
+    /**
+     * @param InputOption[] $options
+     *
+     * @return int
+     */
+    private function calculateTotalWidthForOptions($options)
+    {        
+        $totalWidth = 0;
+        foreach ($options as $option) {
+            $nameLength = 4 + strlen($option->getName()) + 2; // - + shortcut + , + whitespace + name + --
+
+            if ($option->acceptValue()) {
+                $valueLength = 1 + strlen($option->getName()); // = + value
+                $valueLength += $option->isValueOptional() ? 2 : 0; // [ + ]
+
+                $nameLength += $valueLength;
+            }
+            $totalWidth = max($totalWidth, $nameLength);
+        }
+
+        return $totalWidth;
+    }
 }
diff --git a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
index 5054686697a23..8307ea3d5441f 100644
--- a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
@@ -67,6 +67,10 @@ public function getCommandDocument(Command $command)
 
         $commandXML->appendChild($usageXML = $dom->createElement('usage'));
         $usageXML->appendChild($dom->createTextNode(sprintf($command->getSynopsis(), '')));
+        
+        foreach ($command->getUsages() as $usage) {
+            $commandXML->appendChild($dom->createElement('usage', $usage));
+        }
 
         $commandXML->appendChild($descriptionXML = $dom->createElement('description'));
         $descriptionXML->appendChild($dom->createTextNode(str_replace("\n", "\n ", $command->getDescription())));
diff --git a/src/Symfony/Component/Console/Input/InputDefinition.php b/src/Symfony/Component/Console/Input/InputDefinition.php
index 51d1bdd8aa188..3749c90de5fd6 100644
--- a/src/Symfony/Component/Console/Input/InputDefinition.php
+++ b/src/Symfony/Component/Console/Input/InputDefinition.php
@@ -391,22 +391,50 @@ private function shortcutToName($shortcut)
     /**
      * Gets the synopsis.
      *
+     * @param bool $short Whether to return the short version (with options foloded) or not
+     *
      * @return string The synopsis
      */
-    public function getSynopsis()
+    public function getSynopsis($short = false)
     {
         $elements = array();
-        foreach ($this->getOptions() as $option) {
-            $shortcut = $option->getShortcut() ? sprintf('-%s|', $option->getShortcut()) : '';
-            $elements[] = sprintf('['.($option->isValueRequired() ? '%s--%s="..."' : ($option->isValueOptional() ? '%s--%s[="..."]' : '%s--%s')).']', $shortcut, $option->getName());
+        
+        if ($short && $this->getOptions()) {
+            $elements[] = '[options]';
+        } elseif (!$short) {
+            foreach ($this->getOptions() as $option) {
+                $value = '';
+                if ($option->acceptValue()) {
+                    $value = sprintf(
+                        ' %s%s%s',
+                        $option->isValueOptional() ? '[' : '',
+                        strtoupper($option->getName()),
+                        $option->isValueOptional() ? ']' : ''
+                    );
+                }
+
+                $shortcut = $option->getShortcut() ? sprintf('-%s|', $option->getShortcut()) : '';
+                $elements[] = sprintf('[%s--%s%s]', $shortcut, $option->getName(), $value);
+            }
+        }
+
+        if (count($elements) && $this->getArguments()) {
+            $elements[] = '[--]';
         }
 
         foreach ($this->getArguments() as $argument) {
-            $elements[] = sprintf($argument->isRequired() ? '%s' : '[%s]', $argument->getName().($argument->isArray() ? '1' : ''));
+            $element = '<'.$argument->getName().'>';
+            if (!$argument->isRequired()) {
+                $element = '['.$element.']';
+            } elseif ($argument->isArray()) {
+                $element = $element.' ('.$element.')';
+            }
 
             if ($argument->isArray()) {
-                $elements[] = sprintf('... [%sN]', $argument->getName());
+                $element .= '...';
             }
+
+            $elements[] = $element;
         }
 
         return implode(' ', $elements);
diff --git a/src/Symfony/Component/Console/Tests/Command/CommandTest.php b/src/Symfony/Component/Console/Tests/Command/CommandTest.php
index 36c14ddec54fb..b11a00a4abe51 100644
--- a/src/Symfony/Component/Console/Tests/Command/CommandTest.php
+++ b/src/Symfony/Component/Console/Tests/Command/CommandTest.php
@@ -154,8 +154,8 @@ public function testGetSynopsis()
     {
         $command = new \TestCommand();
         $command->addOption('foo');
-        $command->addArgument('foo');
-        $this->assertEquals('namespace:name [--foo] [foo]', $command->getSynopsis(), '->getSynopsis() returns the synopsis');
+        $command->addArgument('bar');
+        $this->assertEquals('namespace:name [--foo] [--] [<bar>]', $command->getSynopsis(), '->getSynopsis() returns the synopsis');
     }
 
     public function testGetHelper()
diff --git a/src/Symfony/Component/Console/Tests/Command/HelpCommandTest.php b/src/Symfony/Component/Console/Tests/Command/HelpCommandTest.php
index ea69c8ba3b508..9e068587f82ba 100644
--- a/src/Symfony/Component/Console/Tests/Command/HelpCommandTest.php
+++ b/src/Symfony/Component/Console/Tests/Command/HelpCommandTest.php
@@ -23,8 +23,10 @@ public function testExecuteForCommandAlias()
         $command = new HelpCommand();
         $command->setApplication(new Application());
         $commandTester = new CommandTester($command);
-        $commandTester->execute(array('command_name' => 'li'));
-        $this->assertRegExp('/list \[--xml\] \[--raw\] \[--format="\.\.\."\] \[namespace\]/', $commandTester->getDisplay(), '->execute() returns a text help for the given command alias');
+        $commandTester->execute(array('command_name' => 'li'), array('decorated' => false));
+        $this->assertContains('list [options] [--] [<namespace>]', $commandTester->getDisplay(), '->execute() returns a text help for the given command alias');
+        $this->assertContains('format=FORMAT', $commandTester->getDisplay(), '->execute() returns a text help for the given command alias');
+        $this->assertContains('raw', $commandTester->getDisplay(), '->execute() returns a text help for the given command alias');
     }
 
     public function testExecuteForCommand()
@@ -32,8 +34,10 @@ public function testExecuteForCommand()
         $command = new HelpCommand();
         $commandTester = new CommandTester($command);
         $command->setCommand(new ListCommand());
-        $commandTester->execute(array());
-        $this->assertRegExp('/list \[--xml\] \[--raw\] \[--format="\.\.\."\] \[namespace\]/', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
+        $commandTester->execute(array(), array('decorated' => false));
+        $this->assertContains('list [options] [--] [<namespace>]', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
+        $this->assertContains('format=FORMAT', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
+        $this->assertContains('raw', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
     }
 
     public function testExecuteForCommandWithXmlOption()
@@ -42,7 +46,7 @@ public function testExecuteForCommandWithXmlOption()
         $commandTester = new CommandTester($command);
         $command->setCommand(new ListCommand());
         $commandTester->execute(array('--format' => 'xml'));
-        $this->assertRegExp('/<command/', $commandTester->getDisplay(), '->execute() returns an XML help text if --xml is passed');
+        $this->assertContains('<command', $commandTester->getDisplay(), '->execute() returns an XML help text if --xml is passed');
     }
 
     public function testExecuteForApplicationCommand()
@@ -50,7 +54,9 @@ public function testExecuteForApplicationCommand()
         $application = new Application();
         $commandTester = new CommandTester($application->get('help'));
         $commandTester->execute(array('command_name' => 'list'));
-        $this->assertRegExp('/list \[--xml\] \[--raw\] \[--format="\.\.\."\] \[namespace\]/', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
+        $this->assertContains('list [options] [--] [<namespace>]', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
+        $this->assertContains('format=FORMAT', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
+        $this->assertContains('raw', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
     }
 
     public function testExecuteForApplicationCommandWithXmlOption()
@@ -58,7 +64,7 @@ public function testExecuteForApplicationCommandWithXmlOption()
         $application = new Application();
         $commandTester = new CommandTester($application->get('help'));
         $commandTester->execute(array('command_name' => 'list', '--format' => 'xml'));
-        $this->assertRegExp('/list \[--xml\] \[--raw\] \[--format="\.\.\."\] \[namespace\]/', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
-        $this->assertRegExp('/<command/', $commandTester->getDisplay(), '->execute() returns an XML help text if --format=xml is passed');
+        $this->assertContains('list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]', $commandTester->getDisplay(), '->execute() returns a text help for the given command');
+        $this->assertContains('<command', $commandTester->getDisplay(), '->execute() returns an XML help text if --format=xml is passed');
     }
 }
diff --git a/src/Symfony/Component/Console/Tests/Command/ListCommandTest.php b/src/Symfony/Component/Console/Tests/Command/ListCommandTest.php
index fbb9feeb68731..3578d48856afb 100644
--- a/src/Symfony/Component/Console/Tests/Command/ListCommandTest.php
+++ b/src/Symfony/Component/Console/Tests/Command/ListCommandTest.php
@@ -22,7 +22,7 @@ public function testExecuteListsCommands()
         $commandTester = new CommandTester($command = $application->get('list'));
         $commandTester->execute(array('command' => $command->getName()), array('decorated' => false));
 
-        $this->assertRegExp('/help   Displays help for a command/', $commandTester->getDisplay(), '->execute() returns a list of available commands');
+        $this->assertRegExp('/help\s{2,}Displays help for a command/', $commandTester->getDisplay(), '->execute() returns a list of available commands');
     }
 
     public function testExecuteListsCommandsWithXmlOption()
diff --git a/src/Symfony/Component/Console/Tests/Descriptor/AbstractDescriptorTest.php b/src/Symfony/Component/Console/Tests/Descriptor/AbstractDescriptorTest.php
index 406c6599ba1ea..f582e7f5ad797 100644
--- a/src/Symfony/Component/Console/Tests/Descriptor/AbstractDescriptorTest.php
+++ b/src/Symfony/Component/Console/Tests/Descriptor/AbstractDescriptorTest.php
@@ -96,7 +96,7 @@ private function getDescriptionTestData(array $objects)
         return $data;
     }
 
-    private function assertDescription($expectedDescription, $describedObject)
+    protected function assertDescription($expectedDescription, $describedObject)
     {
         $output = new BufferedOutput(BufferedOutput::VERBOSITY_NORMAL, true);
         $this->getDescriptor()->describe($output, $describedObject, array('raw_output' => true));
diff --git a/src/Symfony/Component/Console/Tests/Descriptor/JsonDescriptorTest.php b/src/Symfony/Component/Console/Tests/Descriptor/JsonDescriptorTest.php
index 943ea2956a6b3..f9a15612b3f99 100644
--- a/src/Symfony/Component/Console/Tests/Descriptor/JsonDescriptorTest.php
+++ b/src/Symfony/Component/Console/Tests/Descriptor/JsonDescriptorTest.php
@@ -12,6 +12,7 @@
 namespace Symfony\Component\Console\Tests\Descriptor;
 
 use Symfony\Component\Console\Descriptor\JsonDescriptor;
+use Symfony\Component\Console\Output\BufferedOutput;
 
 class JsonDescriptorTest extends AbstractDescriptorTest
 {
@@ -24,4 +25,11 @@ protected function getFormat()
     {
         return 'json';
     }
+
+    protected function assertDescription($expectedDescription, $describedObject)
+    {
+        $output = new BufferedOutput(BufferedOutput::VERBOSITY_NORMAL, true);
+        $this->getDescriptor()->describe($output, $describedObject, array('raw_output' => true));
+        $this->assertEquals(json_decode(trim($expectedDescription), true), json_decode(trim(str_replace(PHP_EOL, "\n", $output->fetch())), true));
+    }
 }
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.json b/src/Symfony/Component/Console/Tests/Fixtures/application_1.json
index 7f8d92eefc1e3..99ad40483e49b 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.json
@@ -1 +1 @@
-{"commands":[{"name":"help","usage":"help [--xml] [--format=\"...\"] [--raw] [command_name]","description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","aliases":[],"definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":"list [--xml] [--raw] [--format=\"...\"] [namespace]","description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","aliases":[],"definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}}],"namespaces":[{"id":"_global","commands":["help","list"]}]}
+{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","aliases":[],"definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","aliases":[],"definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}}],"namespaces":[{"id":"_global","commands":["help","list"]}]}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.md b/src/Symfony/Component/Console/Tests/Fixtures/application_1.md
index e3804162df345..8375c855620f0 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.md
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.md
@@ -8,7 +8,7 @@ help
 ----
 
 * Description: Displays help for a command
-* Usage: `help [--xml] [--format="..."] [--raw] [command_name]`
+* Usage: `help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]`
 * Aliases: <none>
 
 The <info>help</info> command displays help for a given command:
@@ -137,7 +137,7 @@ list
 ----
 
 * Description: Lists commands
-* Usage: `list [--xml] [--raw] [--format="..."] [namespace]`
+* Usage: `list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]`
 * Aliases: <none>
 
 The <info>list</info> command lists all commands:
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_1.txt
index f3a1968effc72..c4cf8f2164cf4 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.txt
@@ -1,17 +1,17 @@
 <info>Console Tool</info>
 
 <comment>Usage:</comment>
- command [options] [arguments]
+  command [options] [arguments]
 
 <comment>Options:</comment>
- <info>--help</info> (-h)           Display this help message
- <info>--quiet</info> (-q)          Do not output any message
- <info>--verbose</info> (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- <info>--version</info> (-V)        Display this application version
- <info>--ansi</info>                Force ANSI output
- <info>--no-ansi</info>             Disable ANSI output
- <info>--no-interaction</info> (-n) Do not ask any interactive question
+  <info>-h, --help</info>            Display this help message
+  <info>-q, --quiet</info>           Do not output any message
+  <info>-V, --version</info>         Display this application version
+  <info>    --ansi</info>            Force ANSI output
+  <info>    --no-ansi</info>         Disable ANSI output
+  <info>-n, --no-interaction</info>  Do not ask any interactive question
+  <info>-v|vv|vvv, --verbose</info>  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
 <comment>Available commands:</comment>
- <info>help  </info> Displays help for a command
- <info>list  </info> Lists commands
+  <info>help</info>  Displays help for a command
+  <info>list</info>  Lists commands
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml b/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml
index 176310886f1d5..b8b9b2ca854b6 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml
@@ -2,7 +2,7 @@
 <symfony>
   <commands>
     <command id="help" name="help">
-      <usage>help [--xml] [--format="..."] [--raw] [command_name]</usage>
+      <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
       <description>Displays help for a command</description>
       <help>The &lt;info&gt;help&lt;/info&gt; command displays help for a given command:
  
@@ -59,7 +59,7 @@
       </options>
     </command>
     <command id="list" name="list">
-      <usage>list [--xml] [--raw] [--format="..."] [namespace]</usage>
+      <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
       <description>Lists commands</description>
       <help>The &lt;info&gt;list&lt;/info&gt; command lists all commands:
  
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.json b/src/Symfony/Component/Console/Tests/Fixtures/application_2.json
index 1655d47e62157..24571615b38e4 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.json
@@ -1 +1 @@
-{"commands":[{"name":"help","usage":"help [--xml] [--format=\"...\"] [--raw] [command_name]","description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","aliases":[],"definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":"list [--xml] [--raw] [--format=\"...\"] [namespace]","description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","aliases":[],"definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}},{"name":"descriptor:command1","usage":"descriptor:command1","description":"command 1 description","help":"command 1 help","aliases":["alias1","alias2"],"definition":{"arguments":[],"options":{"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"descriptor:command2","usage":"descriptor:command2 [-o|--option_name] argument_name","description":"command 2 description","help":"command 2 help","aliases":[],"definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}}],"namespaces":[{"id":"_global","commands":["alias1","alias2","help","list"]},{"id":"descriptor","commands":["descriptor:command1","descriptor:command2"]}]}
+{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","aliases":[],"definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","aliases":[],"definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}},{"name":"descriptor:command1","usage":["descriptor:command1"],"description":"command 1 description","help":"command 1 help","aliases":["alias1","alias2"],"definition":{"arguments":[],"options":{"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message.","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"descriptor:command2","usage":["descriptor:command2 [-o|--option_name] [--] <argument_name>"],"description":"command 2 description","help":"command 2 help","aliases":[],"definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}}],"namespaces":[{"id":"_global","commands":["alias1","alias2","help","list"]},{"id":"descriptor","commands":["descriptor:command1","descriptor:command2"]}]}
\ No newline at end of file
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.md b/src/Symfony/Component/Console/Tests/Fixtures/application_2.md
index 7492886ea3a00..ddc63bf3f32cd 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.md
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.md
@@ -15,7 +15,7 @@ help
 ----
 
 * Description: Displays help for a command
-* Usage: `help [--xml] [--format="..."] [--raw] [command_name]`
+* Usage: `help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]`
 * Aliases: <none>
 
 The <info>help</info> command displays help for a given command:
@@ -144,7 +144,7 @@ list
 ----
 
 * Description: Lists commands
-* Usage: `list [--xml] [--raw] [--format="..."] [namespace]`
+* Usage: `list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]`
 * Aliases: <none>
 
 The <info>list</info> command lists all commands:
@@ -290,7 +290,7 @@ descriptor:command2
 -------------------
 
 * Description: command 2 description
-* Usage: `descriptor:command2 [-o|--option_name] argument_name`
+* Usage: `descriptor:command2 [-o|--option_name] [--] <argument_name>`
 * Aliases: <none>
 
 command 2 help
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_2.txt
index a640a8d2d2e06..292aa829d809d 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.txt
@@ -1,22 +1,22 @@
 <info>My Symfony application</info> version <comment>v1.0</comment>
 
 <comment>Usage:</comment>
- command [options] [arguments]
+  command [options] [arguments]
 
 <comment>Options:</comment>
- <info>--help</info> (-h)           Display this help message
- <info>--quiet</info> (-q)          Do not output any message
- <info>--verbose</info> (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- <info>--version</info> (-V)        Display this application version
- <info>--ansi</info>                Force ANSI output
- <info>--no-ansi</info>             Disable ANSI output
- <info>--no-interaction</info> (-n) Do not ask any interactive question
+  <info>-h, --help</info>            Display this help message
+  <info>-q, --quiet</info>           Do not output any message
+  <info>-V, --version</info>         Display this application version
+  <info>    --ansi</info>            Force ANSI output
+  <info>    --no-ansi</info>         Disable ANSI output
+  <info>-n, --no-interaction</info>  Do not ask any interactive question
+  <info>-v|vv|vvv, --verbose</info>  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
 <comment>Available commands:</comment>
- <info>alias1               </info> command 1 description
- <info>alias2               </info> command 1 description
- <info>help                 </info> Displays help for a command
- <info>list                 </info> Lists commands
-<comment>descriptor</comment>
- <info>descriptor:command1  </info> command 1 description
- <info>descriptor:command2  </info> command 2 description
+  <info>alias1</info>               command 1 description
+  <info>alias2</info>               command 1 description
+  <info>help</info>                 Displays help for a command
+  <info>list</info>                 Lists commands
+ <comment>descriptor</comment>
+  <info>descriptor:command1</info>  command 1 description
+  <info>descriptor:command2</info>  command 2 description
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml b/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml
index a7d65b4f86ce6..5548935685147 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml
@@ -2,7 +2,7 @@
 <symfony name="My Symfony application" version="v1.0">
   <commands>
     <command id="help" name="help">
-      <usage>help [--xml] [--format="..."] [--raw] [command_name]</usage>
+      <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
       <description>Displays help for a command</description>
       <help>The &lt;info&gt;help&lt;/info&gt; command displays help for a given command:
  
@@ -59,7 +59,7 @@
       </options>
     </command>
     <command id="list" name="list">
-      <usage>list [--xml] [--raw] [--format="..."] [namespace]</usage>
+      <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
       <description>Lists commands</description>
       <help>The &lt;info&gt;list&lt;/info&gt; command lists all commands:
  
@@ -132,7 +132,7 @@
       </options>
     </command>
     <command id="descriptor:command2" name="descriptor:command2">
-      <usage>descriptor:command2 [-o|--option_name] argument_name</usage>
+      <usage>descriptor:command2 [-o|--option_name] [--] &lt;argument_name&gt;</usage>
       <description>command 2 description</description>
       <help>command 2 help</help>
       <aliases/>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_astext1.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_astext1.txt
index d9734fe30a416..19dacb23bf7bc 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_astext1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_astext1.txt
@@ -1,20 +1,20 @@
 <info>Console Tool</info>
 
 <comment>Usage:</comment>
- command [options] [arguments]
+  command [options] [arguments]
 
 <comment>Options:</comment>
- <info>--help</info> (-h)           Display this help message
- <info>--quiet</info> (-q)          Do not output any message
- <info>--verbose</info> (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- <info>--version</info> (-V)        Display this application version
- <info>--ansi</info>                Force ANSI output
- <info>--no-ansi</info>             Disable ANSI output
- <info>--no-interaction</info> (-n) Do not ask any interactive question
+  <info>-h, --help</info>            Display this help message
+  <info>-q, --quiet</info>           Do not output any message
+  <info>-V, --version</info>         Display this application version
+  <info>    --ansi</info>            Force ANSI output
+  <info>    --no-ansi</info>         Disable ANSI output
+  <info>-n, --no-interaction</info>  Do not ask any interactive question
+  <info>-v|vv|vvv, --verbose</info>  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
 <comment>Available commands:</comment>
- <info>afoobar  </info> The foo:bar command
- <info>help     </info> Displays help for a command
- <info>list     </info> Lists commands
-<comment>foo</comment>
- <info>foo:bar  </info> The foo:bar command
+  <info>afoobar</info>  The foo:bar command
+  <info>help</info>     Displays help for a command
+  <info>list</info>     Lists commands
+ <comment>foo</comment>
+  <info>foo:bar</info>  The foo:bar command
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_astext2.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_astext2.txt
index 49992cfe3b621..c99ccdda7a6c6 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_astext2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_astext2.txt
@@ -1,16 +1,16 @@
 <info>Console Tool</info>
 
 <comment>Usage:</comment>
- command [options] [arguments]
+  command [options] [arguments]
 
 <comment>Options:</comment>
- <info>--help</info> (-h)           Display this help message
- <info>--quiet</info> (-q)          Do not output any message
- <info>--verbose</info> (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- <info>--version</info> (-V)        Display this application version
- <info>--ansi</info>                Force ANSI output
- <info>--no-ansi</info>             Disable ANSI output
- <info>--no-interaction</info> (-n) Do not ask any interactive question
+  <info>-h, --help</info>            Display this help message
+  <info>-q, --quiet</info>           Do not output any message
+  <info>-V, --version</info>         Display this application version
+  <info>    --ansi</info>            Force ANSI output
+  <info>    --no-ansi</info>         Disable ANSI output
+  <info>-n, --no-interaction</info>  Do not ask any interactive question
+  <info>-v|vv|vvv, --verbose</info>  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
 <comment>Available commands for the "foo" namespace:</comment>
- <info>foo:bar  </info> The foo:bar command
+  <info>foo:bar</info>  The foo:bar command
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt
index d9567819a17f1..21d5384da537f 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt
@@ -2,7 +2,7 @@
 <symfony>
   <commands>
     <command id="help" name="help">
-  <usage>help [--xml] [--format="..."] [--raw] [command_name]</usage>
+  <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
   <description>Displays help for a command</description>
   <help>The &lt;info&gt;help&lt;/info&gt; command displays help for a given command:
  
@@ -59,7 +59,7 @@
   </options>
 </command>
     <command id="list" name="list">
-  <usage>list [--xml] [--raw] [--format="..."] [namespace]</usage>
+  <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
   <description>Lists commands</description>
   <help>The &lt;info&gt;list&lt;/info&gt; command lists all commands:
  
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_renderexception2.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_renderexception2.txt
index c758129bee967..3d9d363b69897 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_renderexception2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_renderexception2.txt
@@ -6,6 +6,6 @@
                                       
 
 
-list [--xml] [--raw] [--format="..."] [namespace]
+list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]
 
 
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_run1.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_run1.txt
index 9bd08b5474c64..0dc2730983f4b 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_run1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_run1.txt
@@ -1,17 +1,17 @@
 Console Tool
 
 Usage:
- command [options] [arguments]
+  command [options] [arguments]
 
 Options:
- --help (-h)           Display this help message
- --quiet (-q)          Do not output any message
- --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- --version (-V)        Display this application version
- --ansi                Force ANSI output
- --no-ansi             Disable ANSI output
- --no-interaction (-n) Do not ask any interactive question
+  -h, --help            Display this help message
+  -q, --quiet           Do not output any message
+  -V, --version         Display this application version
+      --ansi            Force ANSI output
+      --no-ansi         Disable ANSI output
+  -n, --no-interaction  Do not ask any interactive question
+  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
 Available commands:
- help   Displays help for a command
- list   Lists commands
+  help  Displays help for a command
+  list  Lists commands
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_run2.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_run2.txt
index 6963c0f164ef5..4f76997517729 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_run2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_run2.txt
@@ -1,21 +1,21 @@
 Usage:
- help [--xml] [--format="..."] [--raw] [command_name]
+  help [options] [--] [<command_name>]
 
 Arguments:
- command               The command to execute
- command_name          The command name (default: "help")
+  command               The command to execute
+  command_name          The command name [default: "help"]
 
 Options:
- --xml                 To output help as XML
- --format              To output help in other formats (default: "txt")
- --raw                 To output raw command help
- --help (-h)           Display this help message
- --quiet (-q)          Do not output any message
- --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- --version (-V)        Display this application version
- --ansi                Force ANSI output
- --no-ansi             Disable ANSI output
- --no-interaction (-n) Do not ask any interactive question
+      --xml             To output help as XML
+      --format=FORMAT   To output help in other formats [default: "txt"]
+      --raw             To output raw command help
+  -h, --help            Display this help message
+  -q, --quiet           Do not output any message
+  -V, --version         Display this application version
+      --ansi            Force ANSI output
+      --no-ansi         Disable ANSI output
+  -n, --no-interaction  Do not ask any interactive question
+  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
 Help:
  The help command displays help for a given command:
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_run3.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_run3.txt
index 01397755054e4..748982475360f 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_run3.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_run3.txt
@@ -1,13 +1,13 @@
 Usage:
- list [--xml] [--raw] [--format="..."] [namespace]
+  list [options] [--] [<namespace>]
 
 Arguments:
- namespace  The namespace name
+  namespace            The namespace name
 
 Options:
- --xml      To output list as XML
- --raw      To output raw command list
- --format   To output list in other formats (default: "txt")
+      --xml            To output list as XML
+      --raw            To output raw command list
+      --format=FORMAT  To output list in other formats [default: "txt"]
 
 Help:
  The list command lists all commands:
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_1.json b/src/Symfony/Component/Console/Tests/Fixtures/command_1.json
index 0c1675dbcef42..a166bd461883f 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_1.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_1.json
@@ -1 +1 @@
-{"name":"descriptor:command1","usage":"descriptor:command1","description":"command 1 description","help":"command 1 help","aliases":["alias1","alias2"],"definition":{"arguments":[],"options":[]}}
+{"name":"descriptor:command1","usage":["descriptor:command1"],"description":"command 1 description","help":"command 1 help","aliases":["alias1","alias2"],"definition":{"arguments":[],"options":[]}}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt
index 2375ac0e63d8d..6b2b98af9f72d 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt
@@ -1,5 +1,5 @@
 <comment>Usage:</comment>
- descriptor:command1
+  descriptor:command1
 
 <comment>Aliases:</comment> <info>alias1, alias2</info>
 
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.json b/src/Symfony/Component/Console/Tests/Fixtures/command_2.json
index 493b584669ef9..63514f490a772 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.json
@@ -1 +1 @@
-{"name":"descriptor:command2","usage":"descriptor:command2 [-o|--option_name] argument_name","description":"command 2 description","help":"command 2 help","aliases":[],"definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false}}}}
+{"name":"descriptor:command2","usage":["descriptor:command2 [-o|--option_name] [--] <argument_name>"],"description":"command 2 description","help":"command 2 help","aliases":[],"definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false}}}}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.md b/src/Symfony/Component/Console/Tests/Fixtures/command_2.md
index 5257c0d3f2cfc..8b041c00f5872 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.md
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.md
@@ -2,7 +2,7 @@ descriptor:command2
 -------------------
 
 * Description: command 2 description
-* Usage: `descriptor:command2 [-o|--option_name] argument_name`
+* Usage: `descriptor:command2 [-o|--option_name] [--] <argument_name>`
 * Aliases: <none>
 
 command 2 help
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt
index 1da9f3d29fa05..856f3f5c7d14e 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt
@@ -1,11 +1,11 @@
 <comment>Usage:</comment>
- descriptor:command2 [-o|--option_name] argument_name
+  descriptor:command2 [options] [--] <argument_name>
 
 <comment>Arguments:</comment>
- <info>argument_name     </info> 
+  <info>argument_name</info>      
 
 <comment>Options:</comment>
- <info>--option_name</info> (-o) 
+  <info>-o, --option_name</info>  
 
 <comment>Help:</comment>
  command 2 help
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml b/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml
index c411c36c3d285..b349ebf024a93 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <command id="descriptor:command2" name="descriptor:command2">
-  <usage>descriptor:command2 [-o|--option_name] argument_name</usage>
+  <usage>descriptor:command2 [-o|--option_name] [--] &lt;argument_name&gt;</usage>
   <description>command 2 description</description>
   <help>command 2 help</help>
   <aliases/>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt
index 5d703512f7667..804bc6f7134cf 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt
@@ -1,18 +1,19 @@
 <comment>Usage:</comment>
- namespace:name
+  namespace:name
 
 <comment>Aliases:</comment> <info>name</info>
+
 <comment>Arguments:</comment>
- <info>command              </info> The command to execute
+  <info>command</info>               The command to execute
 
 <comment>Options:</comment>
- <info>--help</info> (-h)           Display this help message
- <info>--quiet</info> (-q)          Do not output any message
- <info>--verbose</info> (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- <info>--version</info> (-V)        Display this application version
- <info>--ansi</info>                Force ANSI output
- <info>--no-ansi</info>             Disable ANSI output
- <info>--no-interaction</info> (-n) Do not ask any interactive question
+  <info>-h, --help</info>            Display this help message
+  <info>-q, --quiet</info>           Do not output any message
+  <info>-V, --version</info>         Display this application version
+  <info>    --ansi</info>            Force ANSI output
+  <info>    --no-ansi</info>         Disable ANSI output
+  <info>-n, --no-interaction</info>  Do not ask any interactive question
+  <info>-v|vv|vvv, --verbose</info>  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 
 <comment>Help:</comment>
  help
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/definition_astext.txt b/src/Symfony/Component/Console/Tests/Fixtures/definition_astext.txt
index a7d7e0d5134ec..0431c072ab220 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/definition_astext.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/definition_astext.txt
@@ -1,11 +1,11 @@
 <comment>Arguments:</comment>
- <info>foo       </info> The foo argument
- <info>baz       </info> The baz argument<comment> (default: true)</comment>
- <info>bar       </info> The bar argument<comment> (default: ["http://foo.com/"])</comment>
+  <info>foo</info>                The foo argument
+  <info>baz</info>                The baz argument<comment> [default: true]</comment>
+  <info>bar</info>                The bar argument<comment> [default: ["http://foo.com/"]]</comment>
 
 <comment>Options:</comment>
- <info>--foo</info> (-f) The foo option
- <info>--baz</info>      The baz option<comment> (default: false)</comment>
- <info>--bar</info> (-b) The bar option<comment> (default: "bar")</comment>
- <info>--qux</info>      The qux option<comment> (default: ["http://foo.com/","bar"])</comment><comment> (multiple values allowed)</comment>
- <info>--qux2</info>     The qux2 option<comment> (default: {"foo":"bar"})</comment><comment> (multiple values allowed)</comment>
+  <info>-f, --foo=FOO</info>      The foo option
+  <info>    --baz[=BAZ]</info>    The baz option<comment> [default: false]</comment>
+  <info>-b, --bar[=BAR]</info>    The bar option<comment> [default: "bar"]</comment>
+  <info>    --qux[=QUX]</info>    The qux option<comment> [default: ["http://foo.com/","bar"]]</comment><comment> (multiple values allowed)</comment>
+  <info>    --qux2[=QUX2]</info>  The qux2 option<comment> [default: {"foo":"bar"}]</comment><comment> (multiple values allowed)</comment>
\ No newline at end of file
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_1.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_1.txt
index 111e5157f892d..55035183f67f0 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_1.txt
@@ -1 +1 @@
- <info>argument_name</info>
+  <info>argument_name</info>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_2.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_2.txt
index 9497b1ce01a96..e713660743f75 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_2.txt
@@ -1 +1 @@
- <info>argument_name</info> argument description
+  <info>argument_name</info>  argument description
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_3.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_3.txt
index c421fc9117cad..6b76639e00128 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_3.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_3.txt
@@ -1 +1 @@
- <info>argument_name</info> argument description<comment> (default: "default_value")</comment>
+  <info>argument_name</info>  argument description<comment> [default: "default_value"]</comment>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.txt
index 0db9f66263a71..73b0f308a90ed 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.txt
@@ -1,2 +1,2 @@
 <comment>Arguments:</comment>
- <info>argument_name </info>
+  <info>argument_name</info>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.txt
index c6fb2ccc7b5b1..c02766fd3c113 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.txt
@@ -1,2 +1,2 @@
 <comment>Options:</comment>
- <info>--option_name</info> (-o)
+  <info>-o, --option_name</info>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_4.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_4.txt
index e17c61c3adf4b..63aa81d2d1643 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_4.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_4.txt
@@ -1,5 +1,5 @@
 <comment>Arguments:</comment>
- <info>argument_name     </info> 
+  <info>argument_name</info>      
 
 <comment>Options:</comment>
- <info>--option_name</info> (-o)
+  <info>-o, --option_name</info>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_1.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_option_1.txt
index daf83d07ea748..3a5e4eede487b 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_option_1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_1.txt
@@ -1 +1 @@
- <info>--option_name</info> (-o)
+  <info>-o, --option_name</info>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_2.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_option_2.txt
index 627e3c1ce5db8..1009eff162e6b 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_option_2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_2.txt
@@ -1 +1 @@
- <info>--option_name</info> (-o) option description<comment> (default: "default_value")</comment>
+  <info>-o, --option_name[=OPTION_NAME]</info>  option description<comment> [default: "default_value"]</comment>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_3.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_option_3.txt
index b88b12d2b3e70..947bb6527bb9b 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_option_3.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_3.txt
@@ -1 +1 @@
- <info>--option_name</info> (-o) option description
+  <info>-o, --option_name=OPTION_NAME</info>  option description
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_4.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_option_4.txt
index 5dba5e6e87422..27edf77b4b81a 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/input_option_4.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_4.txt
@@ -1 +1 @@
- <info>--option_name</info> (-o) option description<comment> (multiple values allowed)</comment>
+  <info>-o, --option_name[=OPTION_NAME]</info>  option description<comment> (multiple values allowed)</comment>
diff --git a/src/Symfony/Component/Console/Tests/Input/InputDefinitionTest.php b/src/Symfony/Component/Console/Tests/Input/InputDefinitionTest.php
index 9e3e982d7d4f1..41ccedf469e0f 100644
--- a/src/Symfony/Component/Console/Tests/Input/InputDefinitionTest.php
+++ b/src/Symfony/Component/Console/Tests/Input/InputDefinitionTest.php
@@ -352,25 +352,35 @@ public function testGetOptionDefaults()
         $this->assertEquals($defaults, $definition->getOptionDefaults(), '->getOptionDefaults() returns the default values for all options');
     }
 
-    public function testGetSynopsis()
-    {
-        $definition = new InputDefinition(array(new InputOption('foo')));
-        $this->assertEquals('[--foo]', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
-        $definition = new InputDefinition(array(new InputOption('foo', 'f')));
-        $this->assertEquals('[-f|--foo]', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
-        $definition = new InputDefinition(array(new InputOption('foo', 'f', InputOption::VALUE_REQUIRED)));
-        $this->assertEquals('[-f|--foo="..."]', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
-        $definition = new InputDefinition(array(new InputOption('foo', 'f', InputOption::VALUE_OPTIONAL)));
-        $this->assertEquals('[-f|--foo[="..."]]', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
-
-        $definition = new InputDefinition(array(new InputArgument('foo')));
-        $this->assertEquals('[foo]', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
-        $definition = new InputDefinition(array(new InputArgument('foo', InputArgument::REQUIRED)));
-        $this->assertEquals('foo', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
-        $definition = new InputDefinition(array(new InputArgument('foo', InputArgument::IS_ARRAY)));
-        $this->assertEquals('[foo1] ... [fooN]', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
-        $definition = new InputDefinition(array(new InputArgument('foo', InputArgument::REQUIRED | InputArgument::IS_ARRAY)));
-        $this->assertEquals('foo1 ... [fooN]', $definition->getSynopsis(), '->getSynopsis() returns a synopsis of arguments and options');
+    /**
+     * @dataProvider getGetSynopsisData
+     */
+    public function testGetSynopsis(InputDefinition $definition, $expectedSynopsis, $message = null)
+    {
+        $this->assertEquals($expectedSynopsis, $definition->getSynopsis(), $message ? '->getSynopsis() '.$message : '');
+    }
+
+    public function getGetSynopsisData()
+    {
+        return array(
+            array(new InputDefinition(array(new InputOption('foo'))), '[--foo]', 'puts optional options in square brackets'),
+            array(new InputDefinition(array(new InputOption('foo', 'f'))), '[-f|--foo]', 'separates shortcut with a pipe'),
+            array(new InputDefinition(array(new InputOption('foo', 'f', InputOption::VALUE_REQUIRED))), '[-f|--foo FOO]', 'uses shortcut as value placeholder'),
+            array(new InputDefinition(array(new InputOption('foo', 'f', InputOption::VALUE_OPTIONAL))), '[-f|--foo [FOO]]', 'puts optional values in square brackets'),
+
+            array(new InputDefinition(array(new InputArgument('foo', InputArgument::REQUIRED))), '<foo>', 'puts arguments in angle brackets'),
+            array(new InputDefinition(array(new InputArgument('foo'))), '[<foo>]', 'puts optional arguments in square brackets'),
+            array(new InputDefinition(array(new InputArgument('foo', InputArgument::IS_ARRAY))), '[<foo>]...', 'uses an ellipsis for array arguments'),
+            array(new InputDefinition(array(new InputArgument('foo', InputArgument::REQUIRED | InputArgument::IS_ARRAY))), '<foo> (<foo>)...', 'uses parenthesis and ellipsis for required array arguments'),
+
+            array(new InputDefinition(array(new InputOption('foo'), new InputArgument('foo', InputArgument::REQUIRED))), '[--foo] [--] <foo>', 'puts [--] between options and arguments'),
+        );
+    }
+    
+    public function testGetShortSynopsis()
+    {
+        $definition = new InputDefinition(array(new InputOption('foo'), new InputOption('bar'), new InputArgument('cat')));
+        $this->assertEquals('[options] [--] [<cat>]', $definition->getSynopsis(true), '->getSynopsis(true) groups options in [options]');
     }
 
     public function testLegacyAsText()
@@ -387,6 +397,7 @@ public function testLegacyAsText()
             new InputOption('qux', '', InputOption::VALUE_OPTIONAL | InputOption::VALUE_IS_ARRAY, 'The qux option', array('http://foo.com/', 'bar')),
             new InputOption('qux2', '', InputOption::VALUE_OPTIONAL | InputOption::VALUE_IS_ARRAY, 'The qux2 option', array('foo' => 'bar')),
         ));
+        
         $this->assertStringEqualsFile(self::$fixtures.'/definition_astext.txt', $definition->asText(), '->asText() returns a textual representation of the InputDefinition');
     }
 

From d462abaca6d9e51cc9c9f216bb1a326f1ab3274a Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Thu, 29 Jan 2015 11:39:28 +0100
Subject: [PATCH 3/6] Customize usage section

---
 .../Component/Console/Command/Command.php     |  6 +++--
 .../Console/Descriptor/JsonDescriptor.php     |  3 +--
 .../Console/Descriptor/MarkdownDescriptor.php |  9 +++----
 .../Console/Descriptor/TextDescriptor.php     | 14 +++-------
 .../Console/Descriptor/XmlDescriptor.php      | 14 +++-------
 .../Tests/Fixtures/DescriptorCommand2.php     |  2 ++
 .../Console/Tests/Fixtures/application_1.json |  2 +-
 .../Console/Tests/Fixtures/application_1.md   | 10 ++++---
 .../Console/Tests/Fixtures/application_1.xml  | 10 ++++---
 .../Console/Tests/Fixtures/application_2.json |  2 +-
 .../Console/Tests/Fixtures/application_2.md   | 24 +++++++++++------
 .../Console/Tests/Fixtures/application_2.xml  | 27 +++++++++++--------
 .../Console/Tests/Fixtures/command_1.json     |  2 +-
 .../Console/Tests/Fixtures/command_1.md       |  7 +++--
 .../Console/Tests/Fixtures/command_1.txt      |  4 +--
 .../Console/Tests/Fixtures/command_1.xml      | 10 +++----
 .../Console/Tests/Fixtures/command_2.json     |  2 +-
 .../Console/Tests/Fixtures/command_2.md       |  7 +++--
 .../Console/Tests/Fixtures/command_2.txt      |  2 ++
 .../Console/Tests/Fixtures/command_2.xml      |  7 +++--
 .../DomCrawler/Tests/CrawlerTest.php          |  7 +++++
 21 files changed, 97 insertions(+), 74 deletions(-)

diff --git a/src/Symfony/Component/Console/Command/Command.php b/src/Symfony/Component/Console/Command/Command.php
index 1c1f27c5c66ab..fdfe8a34fa5ca 100644
--- a/src/Symfony/Component/Console/Command/Command.php
+++ b/src/Symfony/Component/Console/Command/Command.php
@@ -574,7 +574,7 @@ public function getAliases()
 
     /**
      * Returns the synopsis for the command.
-     * 
+     *
      * @param bool $short Whether to show the short version of the synopsis (with options folded) or not
      *
      * @return string The synopsis
@@ -582,7 +582,7 @@ public function getAliases()
     public function getSynopsis($short = false)
     {
         $key = $short ? 'short' : 'long';
-        
+
         if (!isset($this->synopsis[$key])) {
             $this->synopsis[$key] = trim(sprintf('%s %s', $this->name, $this->definition->getSynopsis($short)));
         }
@@ -602,6 +602,8 @@ public function addUsage($usage)
         }
 
         $this->usages[] = $usage;
+
+        return $this;
     }
 
     /**
diff --git a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
index 04d98a99f36c2..aef6aebee17c9 100644
--- a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
@@ -157,10 +157,9 @@ private function getCommandData(Command $command)
 
         return array(
             'name' => $command->getName(),
-            'usage' => array_merge(array($command->getSynopsis()), $command->getUsages()),
+            'usage' => array_merge(array($command->getSynopsis()), $command->getUsages(), $command->getAliases()),
             'description' => $command->getDescription(),
             'help' => $command->getProcessedHelp(),
-            'aliases' => $command->getAliases(),
             'definition' => $this->getInputDefinitionData($command->getNativeDefinition()),
         );
     }
diff --git a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
index b29c646129cbb..c629cd96d0391 100644
--- a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
@@ -96,15 +96,14 @@ protected function describeCommand(Command $command, array $options = array())
             $command->getName()."\n"
             .str_repeat('-', strlen($command->getName()))."\n\n"
             .'* Description: '.($command->getDescription() ?: '<none>')."\n"
-            .'* Usage: `'.$command->getSynopsis().'`'."\n"
-            .array_reduce($command->getUsages(), function ($carry, $usage) {
-                return $carry .= '         `'.$usage.'`'."\n";
+            .'* Usage:'."\n\n"
+            .array_reduce(array_merge(array($command->getSynopsis()), $command->getAliases(), $command->getUsages()), function ($carry, $usage) {
+                return $carry .= '  * `'.$usage.'`'."\n";
             })
-            .'* Aliases: '.(count($command->getAliases()) ? '`'.implode('`, `', $command->getAliases()).'`' : '<none>')
         );
 
         if ($help = $command->getProcessedHelp()) {
-            $this->write("\n\n");
+            $this->write("\n");
             $this->write($help);
         }
 
diff --git a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
index 8a60a90cfd31a..5f21999d9b5e0 100644
--- a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
@@ -110,7 +110,7 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
 
         if ($definition->getOptions()) {
             $laterOptions = array();
-            
+
             $this->writeText('<comment>Options:</comment>', $options);
             foreach ($definition->getOptions() as $option) {
                 if (strlen($option->getShortcut()) > 1) {
@@ -137,20 +137,12 @@ protected function describeCommand(Command $command, array $options = array())
         $command->mergeApplicationDefinition(false);
 
         $this->writeText('<comment>Usage:</comment>', $options);
-        $this->writeText("\n");
-        $this->writeText('  '.$command->getSynopsis(true), $options);
-        foreach ($command->getUsages() as $usage) {
+        foreach (array_merge(array($command->getSynopsis(true)), $command->getAliases(), $command->getUsages()) as $usage) {
             $this->writeText("\n");
             $this->writeText('  '.$usage, $options);
         }
         $this->writeText("\n");
 
-        if (count($command->getAliases()) > 0) {
-            $this->writeText("\n");
-            $this->writeText('<comment>Aliases:</comment> <info>'.implode(', ', $command->getAliases()).'</info>', $options);
-            $this->writeText("\n");
-        }
-
         $definition = $command->getNativeDefinition();
         if ($definition->getOptions() || $definition->getArguments()) {
             $this->writeText("\n");
@@ -269,7 +261,7 @@ private function getColumnWidth(array $commands)
      * @return int
      */
     private function calculateTotalWidthForOptions($options)
-    {        
+    {
         $totalWidth = 0;
         foreach ($options as $option) {
             $nameLength = 4 + strlen($option->getName()) + 2; // - + shortcut + , + whitespace + name + --
diff --git a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
index 8307ea3d5441f..30c96981e6734 100644
--- a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
@@ -65,11 +65,11 @@ public function getCommandDocument(Command $command)
         $commandXML->setAttribute('id', $command->getName());
         $commandXML->setAttribute('name', $command->getName());
 
-        $commandXML->appendChild($usageXML = $dom->createElement('usage'));
-        $usageXML->appendChild($dom->createTextNode(sprintf($command->getSynopsis(), '')));
+        $commandXML->appendChild($usagesXML = $dom->createElement('usages'));
+        //$usageXML->appendChild($dom->createTextNode(sprintf($command->getSynopsis(), '')));
         
-        foreach ($command->getUsages() as $usage) {
-            $commandXML->appendChild($dom->createElement('usage', $usage));
+        foreach (array_merge(array($command->getSynopsis()), $command->getAliases(), $command->getUsages()) as $usage) {
+            $usagesXML->appendChild($dom->createElement('usage', $usage));
         }
 
         $commandXML->appendChild($descriptionXML = $dom->createElement('description'));
@@ -78,12 +78,6 @@ public function getCommandDocument(Command $command)
         $commandXML->appendChild($helpXML = $dom->createElement('help'));
         $helpXML->appendChild($dom->createTextNode(str_replace("\n", "\n ", $command->getProcessedHelp())));
 
-        $commandXML->appendChild($aliasesXML = $dom->createElement('aliases'));
-        foreach ($command->getAliases() as $alias) {
-            $aliasesXML->appendChild($aliasXML = $dom->createElement('alias'));
-            $aliasXML->appendChild($dom->createTextNode($alias));
-        }
-
         $definitionXML = $this->getInputDefinitionDocument($command->getNativeDefinition());
         $this->appendDocument($commandXML, $definitionXML->getElementsByTagName('definition')->item(0));
 
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/DescriptorCommand2.php b/src/Symfony/Component/Console/Tests/Fixtures/DescriptorCommand2.php
index bc04ca9141272..51106b96116a6 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/DescriptorCommand2.php
+++ b/src/Symfony/Component/Console/Tests/Fixtures/DescriptorCommand2.php
@@ -23,6 +23,8 @@ protected function configure()
             ->setName('descriptor:command2')
             ->setDescription('command 2 description')
             ->setHelp('command 2 help')
+            ->addUsage('-o|--option_name <argument_name>')
+            ->addUsage('<argument_name>')
             ->addArgument('argument_name', InputArgument::REQUIRED)
             ->addOption('option_name', 'o', InputOption::VALUE_NONE)
         ;
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.json b/src/Symfony/Component/Console/Tests/Fixtures/application_1.json
index 99ad40483e49b..aa4ae9a0dc9d0 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.json
@@ -1 +1 @@
-{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","aliases":[],"definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","aliases":[],"definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}}],"namespaces":[{"id":"_global","commands":["help","list"]}]}
+{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}}],"namespaces":[{"id":"_global","commands":["help","list"]}]}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.md b/src/Symfony/Component/Console/Tests/Fixtures/application_1.md
index 8375c855620f0..c389061389238 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.md
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.md
@@ -8,8 +8,9 @@ help
 ----
 
 * Description: Displays help for a command
-* Usage: `help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]`
-* Aliases: <none>
+* Usage:
+
+  * `help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]`
 
 The <info>help</info> command displays help for a given command:
 
@@ -137,8 +138,9 @@ list
 ----
 
 * Description: Lists commands
-* Usage: `list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]`
-* Aliases: <none>
+* Usage:
+
+  * `list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]`
 
 The <info>list</info> command lists all commands:
 
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml b/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml
index b8b9b2ca854b6..ed84905a06865 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml
@@ -2,7 +2,9 @@
 <symfony>
   <commands>
     <command id="help" name="help">
-      <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
+      <usages>
+        <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
+      </usages>
       <description>Displays help for a command</description>
       <help>The &lt;info&gt;help&lt;/info&gt; command displays help for a given command:
  
@@ -13,7 +15,6 @@
    &lt;info&gt;php app/console help --format=xml list&lt;/info&gt;
  
  To display the list of available commands, please use the &lt;info&gt;list&lt;/info&gt; command.</help>
-      <aliases/>
       <arguments>
         <argument name="command_name" is_required="0" is_array="0">
           <description>The command name</description>
@@ -59,7 +60,9 @@
       </options>
     </command>
     <command id="list" name="list">
-      <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
+      <usages>
+        <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
+      </usages>
       <description>Lists commands</description>
       <help>The &lt;info&gt;list&lt;/info&gt; command lists all commands:
  
@@ -76,7 +79,6 @@
  It's also possible to get raw list of commands (useful for embedding command runner):
  
    &lt;info&gt;php app/console list --raw&lt;/info&gt;</help>
-      <aliases/>
       <arguments>
         <argument name="namespace" is_required="0" is_array="0">
           <description>The namespace name</description>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.json b/src/Symfony/Component/Console/Tests/Fixtures/application_2.json
index 24571615b38e4..241d4813b98b4 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.json
@@ -1 +1 @@
-{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","aliases":[],"definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","aliases":[],"definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}},{"name":"descriptor:command1","usage":["descriptor:command1"],"description":"command 1 description","help":"command 1 help","aliases":["alias1","alias2"],"definition":{"arguments":[],"options":{"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message.","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"descriptor:command2","usage":["descriptor:command2 [-o|--option_name] [--] <argument_name>"],"description":"command 2 description","help":"command 2 help","aliases":[],"definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}}],"namespaces":[{"id":"_global","commands":["alias1","alias2","help","list"]},{"id":"descriptor","commands":["descriptor:command1","descriptor:command2"]}]}
\ No newline at end of file
+{"commands":[{"name":"help","usage":["help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]"],"description":"Displays help for a command","help":"The <info>help<\/info> command displays help for a given command:\n\n  <info>php app\/console help list<\/info>\n\nYou can also output the help in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console help --format=xml list<\/info>\n\nTo display the list of available commands, please use the <info>list<\/info> command.","definition":{"arguments":{"command_name":{"name":"command_name","is_required":false,"is_array":false,"description":"The command name","default":"help"}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output help as XML","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output help in other formats","default":"txt"},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command help","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"list","usage":["list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]"],"description":"Lists commands","help":"The <info>list<\/info> command lists all commands:\n\n  <info>php app\/console list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n  <info>php app\/console list test<\/info>\n\nYou can also output the information in other formats by using the <comment>--format<\/comment> option:\n\n  <info>php app\/console list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n  <info>php app\/console list --raw<\/info>","definition":{"arguments":{"namespace":{"name":"namespace","is_required":false,"is_array":false,"description":"The namespace name","default":null}},"options":{"xml":{"name":"--xml","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output list as XML","default":false},"raw":{"name":"--raw","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"To output raw command list","default":false},"format":{"name":"--format","shortcut":"","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"To output list in other formats","default":"txt"}}}},{"name":"descriptor:command1","usage":["descriptor:command1", "alias1", "alias2"],"description":"command 1 description","help":"command 1 help","definition":{"arguments":[],"options":{"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}},{"name":"descriptor:command2","usage":["descriptor:command2 [-o|--option_name] [--] <argument_name>", "descriptor:command2 -o|--option_name <argument_name>", "descriptor:command2 <argument_name>"],"description":"command 2 description","help":"command 2 help","definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false},"help":{"name":"--help","shortcut":"-h","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this help message","default":false},"quiet":{"name":"--quiet","shortcut":"-q","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not output any message","default":false},"verbose":{"name":"--verbose","shortcut":"-v|-vv|-vvv","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug","default":false},"version":{"name":"--version","shortcut":"-V","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Display this application version","default":false},"ansi":{"name":"--ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Force ANSI output","default":false},"no-ansi":{"name":"--no-ansi","shortcut":"","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Disable ANSI output","default":false},"no-interaction":{"name":"--no-interaction","shortcut":"-n","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"Do not ask any interactive question","default":false}}}}],"namespaces":[{"id":"_global","commands":["alias1","alias2","help","list"]},{"id":"descriptor","commands":["descriptor:command1","descriptor:command2"]}]}
\ No newline at end of file
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.md b/src/Symfony/Component/Console/Tests/Fixtures/application_2.md
index ddc63bf3f32cd..8e0bfd3502530 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.md
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.md
@@ -15,8 +15,9 @@ help
 ----
 
 * Description: Displays help for a command
-* Usage: `help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]`
-* Aliases: <none>
+* Usage:
+
+  * `help [--xml] [--format FORMAT] [--raw] [--] [<command_name>]`
 
 The <info>help</info> command displays help for a given command:
 
@@ -144,8 +145,9 @@ list
 ----
 
 * Description: Lists commands
-* Usage: `list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]`
-* Aliases: <none>
+* Usage:
+
+  * `list [--xml] [--raw] [--format FORMAT] [--] [<namespace>]`
 
 The <info>list</info> command lists all commands:
 
@@ -209,8 +211,11 @@ descriptor:command1
 -------------------
 
 * Description: command 1 description
-* Usage: `descriptor:command1`
-* Aliases: `alias1`, `alias2`
+* Usage:
+
+  * `descriptor:command1`
+  * `alias1`
+  * `alias2`
 
 command 1 help
 
@@ -290,8 +295,11 @@ descriptor:command2
 -------------------
 
 * Description: command 2 description
-* Usage: `descriptor:command2 [-o|--option_name] [--] <argument_name>`
-* Aliases: <none>
+* Usage:
+
+  * `descriptor:command2 [-o|--option_name] [--] <argument_name>`
+  * `descriptor:command2 -o|--option_name <argument_name>`
+  * `descriptor:command2 <argument_name>`
 
 command 2 help
 
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml b/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml
index 5548935685147..18e5db1f64a5e 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml
@@ -2,7 +2,9 @@
 <symfony name="My Symfony application" version="v1.0">
   <commands>
     <command id="help" name="help">
-      <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
+      <usages>
+        <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
+      </usages>
       <description>Displays help for a command</description>
       <help>The &lt;info&gt;help&lt;/info&gt; command displays help for a given command:
  
@@ -13,7 +15,6 @@
    &lt;info&gt;php app/console help --format=xml list&lt;/info&gt;
  
  To display the list of available commands, please use the &lt;info&gt;list&lt;/info&gt; command.</help>
-      <aliases/>
       <arguments>
         <argument name="command_name" is_required="0" is_array="0">
           <description>The command name</description>
@@ -59,7 +60,9 @@
       </options>
     </command>
     <command id="list" name="list">
-      <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
+      <usages>
+        <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
+      </usages>
       <description>Lists commands</description>
       <help>The &lt;info&gt;list&lt;/info&gt; command lists all commands:
  
@@ -76,7 +79,6 @@
  It's also possible to get raw list of commands (useful for embedding command runner):
  
    &lt;info&gt;php app/console list --raw&lt;/info&gt;</help>
-      <aliases/>
       <arguments>
         <argument name="namespace" is_required="0" is_array="0">
           <description>The namespace name</description>
@@ -99,13 +101,13 @@
       </options>
     </command>
     <command id="descriptor:command1" name="descriptor:command1">
-      <usage>descriptor:command1</usage>
+      <usages>
+        <usage>descriptor:command1</usage>
+        <usage>alias1</usage>
+        <usage>alias2</usage>
+      </usages>
       <description>command 1 description</description>
       <help>command 1 help</help>
-      <aliases>
-        <alias>alias1</alias>
-        <alias>alias2</alias>
-      </aliases>
       <arguments/>
       <options>
         <option name="--help" shortcut="-h" accept_value="0" is_value_required="0" is_multiple="0">
@@ -132,10 +134,13 @@
       </options>
     </command>
     <command id="descriptor:command2" name="descriptor:command2">
-      <usage>descriptor:command2 [-o|--option_name] [--] &lt;argument_name&gt;</usage>
+      <usages>
+        <usage>descriptor:command2 [-o|--option_name] [--] &lt;argument_name&gt;</usage>
+        <usage>descriptor:command2 -o|--option_name &lt;argument_name&gt;</usage>
+        <usage>descriptor:command2 &lt;argument_name&gt;</usage>
+      </usages>
       <description>command 2 description</description>
       <help>command 2 help</help>
-      <aliases/>
       <arguments>
         <argument name="argument_name" is_required="1" is_array="0">
           <description></description>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_1.json b/src/Symfony/Component/Console/Tests/Fixtures/command_1.json
index a166bd461883f..20f310b457eb0 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_1.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_1.json
@@ -1 +1 @@
-{"name":"descriptor:command1","usage":["descriptor:command1"],"description":"command 1 description","help":"command 1 help","aliases":["alias1","alias2"],"definition":{"arguments":[],"options":[]}}
+{"name":"descriptor:command1","usage":["descriptor:command1", "alias1", "alias2"],"description":"command 1 description","help":"command 1 help","definition":{"arguments":[],"options":[]}}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_1.md b/src/Symfony/Component/Console/Tests/Fixtures/command_1.md
index 2cef9a2d781ed..34ed3ea7709b3 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_1.md
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_1.md
@@ -2,7 +2,10 @@ descriptor:command1
 -------------------
 
 * Description: command 1 description
-* Usage: `descriptor:command1`
-* Aliases: `alias1`, `alias2`
+* Usage:
+
+  * `descriptor:command1`
+  * `alias1`
+  * `alias2`
 
 command 1 help
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt
index 6b2b98af9f72d..28e14a057a75a 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_1.txt
@@ -1,7 +1,7 @@
 <comment>Usage:</comment>
   descriptor:command1
-
-<comment>Aliases:</comment> <info>alias1, alias2</info>
+  alias1
+  alias2
 
 <comment>Help:</comment>
  command 1 help
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_1.xml b/src/Symfony/Component/Console/Tests/Fixtures/command_1.xml
index dcfa6fa5044e7..838b9bd91f837 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_1.xml
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_1.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <command id="descriptor:command1" name="descriptor:command1">
-  <usage>descriptor:command1</usage>
+  <usages>
+    <usage>descriptor:command1</usage>
+    <usage>alias1</usage>
+    <usage>alias2</usage>
+  </usages>
   <description>command 1 description</description>
   <help>command 1 help</help>
-  <aliases>
-    <alias>alias1</alias>
-    <alias>alias2</alias>
-  </aliases>
   <arguments/>
   <options/>
 </command>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.json b/src/Symfony/Component/Console/Tests/Fixtures/command_2.json
index 63514f490a772..38edd1e2098db 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.json
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.json
@@ -1 +1 @@
-{"name":"descriptor:command2","usage":["descriptor:command2 [-o|--option_name] [--] <argument_name>"],"description":"command 2 description","help":"command 2 help","aliases":[],"definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false}}}}
+{"name":"descriptor:command2","usage":["descriptor:command2 [-o|--option_name] [--] <argument_name>", "descriptor:command2 -o|--option_name <argument_name>", "descriptor:command2 <argument_name>"],"description":"command 2 description","help":"command 2 help","definition":{"arguments":{"argument_name":{"name":"argument_name","is_required":true,"is_array":false,"description":"","default":null}},"options":{"option_name":{"name":"--option_name","shortcut":"-o","accept_value":false,"is_value_required":false,"is_multiple":false,"description":"","default":false}}}}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.md b/src/Symfony/Component/Console/Tests/Fixtures/command_2.md
index 8b041c00f5872..6f538b6407947 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.md
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.md
@@ -2,8 +2,11 @@ descriptor:command2
 -------------------
 
 * Description: command 2 description
-* Usage: `descriptor:command2 [-o|--option_name] [--] <argument_name>`
-* Aliases: <none>
+* Usage:
+
+  * `descriptor:command2 [-o|--option_name] [--] <argument_name>`
+  * `descriptor:command2 -o|--option_name <argument_name>`
+  * `descriptor:command2 <argument_name>`
 
 command 2 help
 
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt
index 856f3f5c7d14e..72f7ce05869d2 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt
@@ -1,5 +1,7 @@
 <comment>Usage:</comment>
   descriptor:command2 [options] [--] <argument_name>
+  descriptor:command2 -o|--option_name <argument_name>
+  descriptor:command2 <argument_name>
 
 <comment>Arguments:</comment>
   <info>argument_name</info>      
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml b/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml
index b349ebf024a93..67364caa4ede3 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml
@@ -1,9 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <command id="descriptor:command2" name="descriptor:command2">
-  <usage>descriptor:command2 [-o|--option_name] [--] &lt;argument_name&gt;</usage>
+  <usages>
+    <usage>descriptor:command2 [-o|--option_name] [--] &lt;argument_name&gt;</usage>
+    <usage>descriptor:command2 -o|--option_name &lt;argument_name&gt;</usage>
+    <usage>descriptor:command2 &lt;argument_name&gt;</usage>
+  </usages>
   <description>command 2 description</description>
   <help>command 2 help</help>
-  <aliases/>
   <arguments>
     <argument name="argument_name" is_required="1" is_array="0">
       <description></description>
diff --git a/src/Symfony/Component/DomCrawler/Tests/CrawlerTest.php b/src/Symfony/Component/DomCrawler/Tests/CrawlerTest.php
index 82045a1dd5ae3..0db328a662946 100755
--- a/src/Symfony/Component/DomCrawler/Tests/CrawlerTest.php
+++ b/src/Symfony/Component/DomCrawler/Tests/CrawlerTest.php
@@ -986,6 +986,13 @@ public function getBaseTagWithFormData()
         );
     }
 
+    public function testCountOfNestedElements()
+    {
+        $crawler = new Crawler('<html><body><ul><li>List item 1<ul><li>Sublist item 1</li><li>Sublist item 2</ul></li></ul></body></html>');
+
+        $this->assertCount(1, $crawler->filter('li:contains("List item 1")'));
+    }
+
     public function createTestCrawler($uri = null)
     {
         $dom = new \DOMDocument();

From d9a42c94e97a75a6db90a219db80630a3a1b6f1b Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Tue, 17 Feb 2015 20:29:06 +0100
Subject: [PATCH 4/6] Fixed some more tests

---
 .../Tests/Fixtures/application_asxml1.txt      | 18 ++++++++++--------
 .../Tests/Fixtures/application_asxml2.txt      |  8 ++++----
 .../Console/Tests/Fixtures/command_astext.txt  |  3 +--
 .../Console/Tests/Fixtures/command_asxml.txt   |  8 ++++----
 4 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt
index 21d5384da537f..edc9d3f894ac2 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_asxml1.txt
@@ -2,7 +2,9 @@
 <symfony>
   <commands>
     <command id="help" name="help">
-  <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
+    <usages>
+      <usage>help [--xml] [--format FORMAT] [--raw] [--] [&lt;command_name&gt;]</usage>
+    </usages>
   <description>Displays help for a command</description>
   <help>The &lt;info&gt;help&lt;/info&gt; command displays help for a given command:
  
@@ -13,7 +15,6 @@
    &lt;info&gt;php app/console help --format=xml list&lt;/info&gt;
  
  To display the list of available commands, please use the &lt;info&gt;list&lt;/info&gt; command.</help>
-  <aliases />
   <arguments>
     <argument name="command_name" is_required="0" is_array="0">
       <description>The command name</description>
@@ -59,7 +60,9 @@
   </options>
 </command>
     <command id="list" name="list">
-  <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
+    <usages>
+      <usage>list [--xml] [--raw] [--format FORMAT] [--] [&lt;namespace&gt;]</usage>
+    </usages>
   <description>Lists commands</description>
   <help>The &lt;info&gt;list&lt;/info&gt; command lists all commands:
  
@@ -76,7 +79,6 @@
  It's also possible to get raw list of commands (useful for embedding command runner):
  
    &lt;info&gt;php app/console list --raw&lt;/info&gt;</help>
-  <aliases/>
   <arguments>
     <argument name="namespace" is_required="0" is_array="0">
       <description>The namespace name</description>
@@ -99,12 +101,12 @@
   </options>
 </command>
     <command id="foo:bar" name="foo:bar">
-  <usage>foo:bar</usage>
+    <usages>
+      <usage>foo:bar</usage>
+      <usage>afoobar</usage>
+    </usages>
   <description>The foo:bar command</description>
   <help/>
-  <aliases>
-    <alias>afoobar</alias>
-  </aliases>
   <arguments/>
     <options>
       <option name="--help" shortcut="-h" accept_value="0" is_value_required="0" is_multiple="0">
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_asxml2.txt b/src/Symfony/Component/Console/Tests/Fixtures/application_asxml2.txt
index 0b30b201f2ff7..8fa3b699eba03 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/application_asxml2.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/application_asxml2.txt
@@ -2,12 +2,12 @@
 <symfony>
   <commands namespace="foo">
     <command id="foo:bar" name="foo:bar">
-  <usage>foo:bar</usage>
+    <usages>
+      <usage>foo:bar</usage>
+      <usage>afoobar</usage>
+    </usages>
   <description>The foo:bar command</description>
   <help/>
-  <aliases>
-    <alias>afoobar</alias>
-  </aliases>
   <arguments/>
     <options>
       <option name="--help" shortcut="-h" accept_value="0" is_value_required="0" is_multiple="0">
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt
index 804bc6f7134cf..7e206388078db 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_astext.txt
@@ -1,7 +1,6 @@
 <comment>Usage:</comment>
   namespace:name
-
-<comment>Aliases:</comment> <info>name</info>
+  name
 
 <comment>Arguments:</comment>
   <info>command</info>               The command to execute
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_asxml.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_asxml.txt
index 57542faad5b8f..5e776238aa0a1 100644
--- a/src/Symfony/Component/Console/Tests/Fixtures/command_asxml.txt
+++ b/src/Symfony/Component/Console/Tests/Fixtures/command_asxml.txt
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <command id="namespace:name" name="namespace:name">
-  <usage>namespace:name</usage>
+  <usages>
+    <usage>namespace:name</usage>
+    <usage>name</usage>
+  </usages>
   <description>description</description>
   <help>help</help>
-  <aliases>
-    <alias>name</alias>
-  </aliases>
   <arguments>
     <argument name="command" is_required="1" is_array="0">
       <description>The command to execute</description>

From 749d9cfba65fdcf81301473200f7f55b7f724e31 Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Wed, 18 Feb 2015 15:40:57 +0100
Subject: [PATCH 5/6] Added test for multiline descriptions

---
 .../Component/Console/Descriptor/JsonDescriptor.php    |  4 ++--
 .../Console/Descriptor/MarkdownDescriptor.php          |  4 ++--
 .../Component/Console/Descriptor/TextDescriptor.php    |  6 ++++--
 .../Console/Tests/Descriptor/ObjectsProvider.php       |  2 ++
 .../Console/Tests/Fixtures/input_argument_4.json       |  1 +
 .../Console/Tests/Fixtures/input_argument_4.md         |  8 ++++++++
 .../Console/Tests/Fixtures/input_argument_4.txt        |  2 ++
 .../Console/Tests/Fixtures/input_argument_4.xml        |  6 ++++++
 .../Console/Tests/Fixtures/input_option_5.json         |  1 +
 .../Component/Console/Tests/Fixtures/input_option_5.md | 10 ++++++++++
 .../Console/Tests/Fixtures/input_option_5.txt          |  2 ++
 .../Console/Tests/Fixtures/input_option_5.xml          |  6 ++++++
 12 files changed, 46 insertions(+), 6 deletions(-)
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.json
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.md
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.txt
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.xml
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_option_5.json
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_option_5.md
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_option_5.txt
 create mode 100644 src/Symfony/Component/Console/Tests/Fixtures/input_option_5.xml

diff --git a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
index aef6aebee17c9..8649d3ac456f3 100644
--- a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
@@ -102,7 +102,7 @@ private function getInputArgumentData(InputArgument $argument)
             'name' => $argument->getName(),
             'is_required' => $argument->isRequired(),
             'is_array' => $argument->isArray(),
-            'description' => $argument->getDescription(),
+            'description' => preg_replace('/\s*\R\s*/', ' ', $argument->getDescription()),
             'default' => $argument->getDefault(),
         );
     }
@@ -120,7 +120,7 @@ private function getInputOptionData(InputOption $option)
             'accept_value' => $option->acceptValue(),
             'is_value_required' => $option->isValueRequired(),
             'is_multiple' => $option->isArray(),
-            'description' => $option->getDescription(),
+            'description' => preg_replace('/\s*\R\s*/', ' ', $option->getDescription()),
             'default' => $option->getDefault(),
         );
     }
diff --git a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
index c629cd96d0391..10f05168d47d0 100644
--- a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
@@ -36,7 +36,7 @@ protected function describeInputArgument(InputArgument $argument, array $options
             .'* Name: '.($argument->getName() ?: '<none>')."\n"
             .'* Is required: '.($argument->isRequired() ? 'yes' : 'no')."\n"
             .'* Is array: '.($argument->isArray() ? 'yes' : 'no')."\n"
-            .'* Description: '.($argument->getDescription() ?: '<none>')."\n"
+            .'* Description: '.preg_replace('/\s*\R\s*/', PHP_EOL.'  ', $argument->getDescription() ?: '<none>')."\n"
             .'* Default: `'.str_replace("\n", '', var_export($argument->getDefault(), true)).'`'
         );
     }
@@ -53,7 +53,7 @@ protected function describeInputOption(InputOption $option, array $options = arr
             .'* Accept value: '.($option->acceptValue() ? 'yes' : 'no')."\n"
             .'* Is value required: '.($option->isValueRequired() ? 'yes' : 'no')."\n"
             .'* Is multiple: '.($option->isArray() ? 'yes' : 'no')."\n"
-            .'* Description: '.($option->getDescription() ?: '<none>')."\n"
+            .'* Description: '.preg_replace('/\s*\R\s*/', PHP_EOL.'  ', $option->getDescription() ?: '<none>')."\n"
             .'* Default: `'.str_replace("\n", '', var_export($option->getDefault(), true)).'`'
         );
     }
diff --git a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
index 5f21999d9b5e0..07f63c21c0974 100644
--- a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
@@ -43,7 +43,8 @@ protected function describeInputArgument(InputArgument $argument, array $options
         $this->writeText(sprintf("  <info>%s</info>%s%s%s",
             $argument->getName(),
             str_repeat(' ', $spacingWidth),
-            str_replace("\n", "\n".str_repeat(' ', $totalWidth + 4), $argument->getDescription()),
+            // + 17 = 2 spaces + <info> + </info> + 2 spaces
+            preg_replace('/\s*\R\s*/', PHP_EOL.str_repeat(' ', $totalWidth + 17), $argument->getDescription()),
             $default
         ), $options);
     }
@@ -79,7 +80,8 @@ protected function describeInputOption(InputOption $option, array $options = arr
         $this->writeText(sprintf("  <info>%s</info>%s%s%s%s",
             $synopsis,
             str_repeat(' ', $spacingWidth),
-            str_replace("\n", "\n".str_repeat(' ', $totalWidth + 4), $option->getDescription()),
+            // + 17 = 2 spaces + <info> + </info> + 2 spaces
+            preg_replace('/\s*\R\s*/', "\n".str_repeat(' ', $totalWidth + 17), $option->getDescription()),
             $default,
             $option->isArray() ? '<comment> (multiple values allowed)</comment>' : ''
         ), $options);
diff --git a/src/Symfony/Component/Console/Tests/Descriptor/ObjectsProvider.php b/src/Symfony/Component/Console/Tests/Descriptor/ObjectsProvider.php
index a3c49d74fe048..1f40d2e6a02e7 100644
--- a/src/Symfony/Component/Console/Tests/Descriptor/ObjectsProvider.php
+++ b/src/Symfony/Component/Console/Tests/Descriptor/ObjectsProvider.php
@@ -30,6 +30,7 @@ public static function getInputArguments()
             'input_argument_1' => new InputArgument('argument_name', InputArgument::REQUIRED),
             'input_argument_2' => new InputArgument('argument_name', InputArgument::IS_ARRAY, 'argument description'),
             'input_argument_3' => new InputArgument('argument_name', InputArgument::OPTIONAL, 'argument description', 'default_value'),
+            'input_argument_4' => new InputArgument('argument_name', InputArgument::REQUIRED, "multiline\nargument description"),
         );
     }
 
@@ -40,6 +41,7 @@ public static function getInputOptions()
             'input_option_2' => new InputOption('option_name', 'o', InputOption::VALUE_OPTIONAL, 'option description', 'default_value'),
             'input_option_3' => new InputOption('option_name', 'o', InputOption::VALUE_REQUIRED, 'option description'),
             'input_option_4' => new InputOption('option_name', 'o', InputOption::VALUE_IS_ARRAY | InputOption::VALUE_OPTIONAL, 'option description', array()),
+            'input_option_5' => new InputOption('option_name', 'o', InputOption::VALUE_REQUIRED, "multiline\noption description"),
         );
     }
 
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.json b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.json
new file mode 100644
index 0000000000000..8067a4d1b1279
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.json
@@ -0,0 +1 @@
+{"name":"argument_name","is_required":true,"is_array":false,"description":"multiline argument description","default":null}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.md b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.md
new file mode 100644
index 0000000000000..f026ab37672bf
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.md
@@ -0,0 +1,8 @@
+**argument_name:**
+
+* Name: argument_name
+* Is required: yes
+* Is array: no
+* Description: multiline
+  argument description
+* Default: `NULL`
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.txt
new file mode 100644
index 0000000000000..aa74e8ceb2507
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.txt
@@ -0,0 +1,2 @@
+  <info>argument_name</info>  multiline
+                              argument description
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.xml b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.xml
new file mode 100644
index 0000000000000..5ca135ec2cb48
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_argument_4.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<argument name="argument_name" is_required="1" is_array="0">
+  <description>multiline
+argument description</description>
+  <defaults/>
+</argument>
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.json b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.json
new file mode 100644
index 0000000000000..35a1405fa436d
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.json
@@ -0,0 +1 @@
+{"name":"--option_name","shortcut":"-o","accept_value":true,"is_value_required":true,"is_multiple":false,"description":"multiline option description","default":null}
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.md b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.md
new file mode 100644
index 0000000000000..82f51cad30ddf
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.md
@@ -0,0 +1,10 @@
+**option_name:**
+
+* Name: `--option_name`
+* Shortcut: `-o`
+* Accept value: yes
+* Is value required: yes
+* Is multiple: no
+* Description: multiline
+  option description
+* Default: `NULL`
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.txt b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.txt
new file mode 100644
index 0000000000000..4368883cc7217
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.txt
@@ -0,0 +1,2 @@
+  <info>-o, --option_name=OPTION_NAME</info>  multiline
+                                              option description
diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.xml b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.xml
new file mode 100644
index 0000000000000..90040ccd02987
--- /dev/null
+++ b/src/Symfony/Component/Console/Tests/Fixtures/input_option_5.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<option name="--option_name" shortcut="-o" accept_value="1" is_value_required="1" is_multiple="0">
+  <description>multiline
+option description</description>
+  <defaults/>
+</option>

From 7489720c4b3cf3df598e91a5315d378cd1d56572 Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Wed, 18 Feb 2015 17:42:19 +0100
Subject: [PATCH 6/6] Made fabbot happy

---
 src/Symfony/Component/Console/Descriptor/TextDescriptor.php | 2 +-
 src/Symfony/Component/Console/Descriptor/XmlDescriptor.php  | 3 +--
 src/Symfony/Component/Console/Input/InputDefinition.php     | 2 +-
 3 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
index 07f63c21c0974..37bae0663edcd 100644
--- a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php
@@ -183,7 +183,7 @@ protected function describeApplication(Application $application, array $options
 
             $this->writeText("<comment>Usage:</comment>\n", $options);
             $this->writeText("  command [options] [arguments]\n\n", $options);
-            
+
             $this->describeInputDefinition(new InputDefinition($application->getDefinition()->getOptions()), $options);
 
             $this->writeText("\n");
diff --git a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
index 30c96981e6734..b5676beb3766f 100644
--- a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
+++ b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
@@ -66,8 +66,7 @@ public function getCommandDocument(Command $command)
         $commandXML->setAttribute('name', $command->getName());
 
         $commandXML->appendChild($usagesXML = $dom->createElement('usages'));
-        //$usageXML->appendChild($dom->createTextNode(sprintf($command->getSynopsis(), '')));
-        
+
         foreach (array_merge(array($command->getSynopsis()), $command->getAliases(), $command->getUsages()) as $usage) {
             $usagesXML->appendChild($dom->createElement('usage', $usage));
         }
diff --git a/src/Symfony/Component/Console/Input/InputDefinition.php b/src/Symfony/Component/Console/Input/InputDefinition.php
index 3749c90de5fd6..7efb849ab2470 100644
--- a/src/Symfony/Component/Console/Input/InputDefinition.php
+++ b/src/Symfony/Component/Console/Input/InputDefinition.php
@@ -398,7 +398,7 @@ private function shortcutToName($shortcut)
     public function getSynopsis($short = false)
     {
         $elements = array();
-        
+
         if ($short && $this->getOptions()) {
             $elements[] = '[options]';
         } elseif (!$short) {