minor #9387 Clarify how to use short options with values. (greg-1-anderson, javiereguiluz)

This PR was submitted for the master branch but it was merged into the 2.7 branch instead (closes #9387).

Discussion
----------

Clarify how to use short options with values.

Adds a brief description of the correct syntax for short options that take values.

Related to symfony/symfony#26378

Commits
-------

926461a Removed a duplicated content
194e541 Minor tweaks
2eddcf1 Clarify Symfony Console option conventions
2cf4122 Wrap long lines
f4b77be Clarify how to use short options with values.

Author: javiereguiluz

console/input.rst

@@ -174,6 +174,11 @@ flag:
                 1
             );
 
+Note that to comply with the `docopt standard`_, long options can specify their
+values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or
+``--iterations=5``), but short options can only use white spaces or no
+separation at all (e.g. ``-i 5`` or ``-i5``).
+
 There are four option variants you can use:
 
 ``InputOption::VALUE_IS_ARRAY``
@@ -184,8 +189,8 @@ There are four option variants you can use:
     behavior of options;
 
 ``InputOption::VALUE_REQUIRED``
-    This value is required (e.g. ``--iterations=5``), the option itself is
-    still optional;
+    This value is required (e.g. ``--iterations=5`` or ``-i5``), the option
+    itself is still optional;
 
 ``InputOption::VALUE_OPTIONAL``
     This option may or may not have a value (e.g. ``--yell`` or
@@ -215,3 +220,14 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or
     Similarly, due to a PHP limitation, there is no way to pass an empty string
     as the value of an option. In ``command --prefix`` and ``command --prefix=''``
     cases, the value of the ``prefix`` option will be ``null``.
+
+.. caution::
+
+    While it is possible to separate an option from its value with a white space,
+    using this form leads to an ambiguity should the option appear before the
+    command name. For example, ``php bin/console --iterations 5 app:greet Fabien``
+    is ambiguous; Symfony would interpret ``5`` as the command name. To avoid
+    this situation, always place options after the command name, or avoid using
+    a space to separate the option name from its value.
+
+.. _`docopt standard`: http://docopt.org/