diff --git a/components/console/console_arguments.rst b/components/console/console_arguments.rst
new file mode 100644
index 00000000000..1212e96d955
--- /dev/null
+++ b/components/console/console_arguments.rst
@@ -0,0 +1,84 @@
+.. index::
+    single: Console; Console arguments
+
+Understand how Console Arguments are Handled
+============================================
+
+It can be difficult to understand the way arguments are handled by the console application.
+The Symfony Console application, like many other CLI utility tools, follows the behavior
+described in the `docopt`_ standards.
+
+Let's see a complete example on how the arguments are understood by Console application,
+regarding to the Console Options or Arguments defined in the application::
+
+   namespace Acme\Console\Command;
+
+      use Symfony\Component\Console\Command\Command;
+      use Symfony\Component\Console\Input\InputArgument;
+      use Symfony\Component\Console\Input\InputInterface;
+      use Symfony\Component\Console\Input\InputOption;
+      use Symfony\Component\Console\Output\OutputInterface;
+
+      class DemoArgsCommand extends Command
+      {
+        protected function configure()
+        {
+            $this
+                ->setName('demo:args')
+                ->setDescription('Describe args behaviors')
+                ->setDefinition(
+                    new InputDefinition(array(
+                        new InputOption('foo', 'f'),
+                        new InputOption('bar', 'br', InputOption::VALUE_REQUIRED),
+                        new InputOption('baz', 'bz', InputOption::VALUE_OPTIONAL)
+                    )
+                )
+            ;
+        }
+
+        protected function execute(InputInterface $input, OutputInterface $output)
+        {
+           // ...
+        }
+      }
+
+Let's take a look to the values results for differents inputs:
+
+====================  =========================================
+Input                 Values
+====================  =========================================
+--bar=Hello           foo = false, bar = "Hello"
+--bar Hello           foo = false, bar = "Hello"
+-br=Hello             foo = false, bar = "Hello"
+-br Hello             foo = false, bar = "Hello"
+-brHello              foo = false, bar = "Hello"
+-fbzWorld -br Hello   foo = true, bar = "Hello", baz = "World"
+-bzfWorld -br Hello   foo = false, bar = "Hello", baz ="fWorld"
+-bzbrWorld            foo = false, bz = "brWorld", baz = null
+====================  =========================================
+
+
+Now, assume there is also an optional argument in the input definition::
+
+   new InputDefinition(array(
+       // ...
+       new InputArgument('arg', InputArgument::OPTIONAL),
+   ));
+
+==========================  ========================================
+Input                       Values
+==========================  ========================================
+--bar Hello                 bar = "Hello", arg = null
+--bar Hello World           bar = "Hello", arg = "World"
+--bar Hello --baz World     bar = "Hello", baz = "World", arg = null
+--bar Hello --baz -- World  bar = "Hello", baz = null, arg = "World"
+-b Hello -bz World          bar = "Hello", baz = "World", arg = null
+==========================  ========================================
+
+The fourth example shows the special ``--`` seperator which -as you can read
+in docopt- seperates the options from the arguments. By that, ``World`` is
+no longer interpreted as a value of the ``baz`` option (which has an optional value),
+but as the value for the argument.
+
+.. _docopt: http://docopt.org/
+
diff --git a/components/console/index.rst b/components/console/index.rst
index c814942d018..b46548de647 100644
--- a/components/console/index.rst
+++ b/components/console/index.rst
@@ -7,5 +7,6 @@ Console
     introduction
     usage
     single_command_tool
+    console_arguments
     events
     helpers/index
diff --git a/components/console/introduction.rst b/components/console/introduction.rst
index cffbfabaddf..b39d31902b9 100644
--- a/components/console/introduction.rst
+++ b/components/console/introduction.rst
@@ -292,7 +292,7 @@ declare a one-letter shortcut that you can call with a single dash like
 .. tip::
 
     It is also possible to make an option *optionally* accept a value (so that
-    ``--yell`` or ``--yell=loud`` work). Options can also be configured to
+    ``--yell`` or ``--yell=loud`` or ``--yell loud`` work). Options can also be configured to
     accept an array of values.
 
 For example, add a new option to the command that can be used to specify
@@ -492,6 +492,7 @@ Learn More!
 * :doc:`/components/console/usage`
 * :doc:`/components/console/single_command_tool`
 * :doc:`/components/console/events`
+* :doc:`/components/console/console_arguments`
 
 .. _Packagist: https://packagist.org/packages/symfony/console
 .. _ANSICON: https://github.com/adoxa/ansicon/releases
diff --git a/components/console/single_command_tool.rst b/components/console/single_command_tool.rst
index 8f2dac46f2c..36c7d54818e 100644
--- a/components/console/single_command_tool.rst
+++ b/components/console/single_command_tool.rst
@@ -1,5 +1,5 @@
 .. index::
-   single: Console; Single command application
+    single: Console; Single command application
 
 Building a Single Command Application
 =====================================