Clarify how to use short options with values.

[greg-1-anderson]

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

Related to symfony/symfony#26378

[javiereguiluz]

@greg-1-anderson thanks for contributing this clarification and for your help in the related code issue. I like your proposal, but I feel like it's missing some information. If it's correct, what do you think about expanding your original description like this:

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``).

.. _`docopt standard`: http://docopt.org/

[greg-1-anderson]

@javiereguiluz I like your improvement. There is one problem that remains, though, and that is that Symfony fetches the command name via getFirstArgument(), and that method always takes the literal first argument, i.e. the first one that does not start with a -, without any consideration that said argument might actually be the value of some option that came before (e.g. --foo BAR or -f BAR). It's hard to fix this behavior in code, though, because Symfony needs to know the command name before it can apply the command-specific option definitions.

Perhaps this should be explained in the documentation as well? I'll try taking a pass a this.

[javiereguiluz]

@greg-1-anderson thanks for helping us improve the docs and congrats on your first Symfony Docs contribution. It was a really nice first contribution! Note: we merged it on 2.7 branch, the oldest maintained branch. That's why GitHub displays it as closed instead of merged, but it's merged.

[Neirda24]

@javiereguiluz , @greg-1-anderson ⚠️ :

$ ./bin/console -e dev


  Command "dev" is not defined.

or

$ ./bin/console --env dev


  Command "dev" is not defined.

If no command is provided these forms does not work as well.

So in the end we have:

$ ./bin/console -e dev
# Or
$ ./bin/console --env=dev

that are working only.

[greg-1-anderson]

@Neirda24 This is explained in the caution section of this PR.

[Neirda24]

No I mean if you don't specify any command it won't work. It might be good to add it in the caution. Or even just say to always use only the ones that work every time which are :

$ ./bin/console -e dev
# Or
$ ./bin/console --env=dev

[greg-1-anderson]

@Neirda24 First off, I think you might have a typo above. Did you mean to say that the things that always work are:

$ ./bin/console -edev
# Or
$ ./bin/console --env=dev

n.b. no space in short option.

My opinion is that the current version of the docs are unambiguous, but things can always be improved. I think the best thing to do to further improve the text would be to open a new PR with the suggested changes.

[Neirda24]

@greg-1-anderson . Yeah sorry for my typo. Agreed. Thanks