Re: [PATCH v3] rev-parse --parseopt: option argument name hints

[Ilya Bobyr <ilya.bobyr@gmail.com>]

On 3/20/2014 4:19 PM, Ilya Bobyr wrote:
> On 3/20/2014 11:38 AM, Junio C Hamano wrote:
>> Ilya Bobyr <ilya.bobyr@gmail.com> writes:
>>
>>> [...]
>>>     ------------
>>> -<opt_spec><flags>* SP+ help LF
>>> +<opt_spec><flags>*<arg_hint>? SP+ help LF
>>>   ------------
>>>     `<opt_spec>`::
>>> @@ -313,6 +313,12 @@ Each line of options has this format:
>>>         * Use `!` to not make the corresponding negated long option
>>> available.
>>>   +`<arg_hint>`::
>>> +    `<arg_hing>`, if specified, is used as a name of the argument
>>> in the
>>> +    help output, for options that take arguments. `<arg_hint>` is
>>> +    terminated by the first whitespace. When output the name is
>>> shown in
>>> +    angle braces.  Underscore symbols are replaced with spaces.
>> The last part is troubling (and sounds not very sane).  Do we do
>> such a munging anywhere else, or is it just here?  If the latter I'd
>> prefer not to see such a hack.
>
> The following commands have spaces in argument names in the "-h"
> output for one or two arguments:
>   * clone
s/clone/checkout/
>   * commit
>   * merge
>
> A number of commands use dashes to separate words in arguments names.
>
> "git notes" is the only command that uses an underscore in one
> argument name.
>
> At the moment space is used to separate option specification from the
> help line.  As argument name hint is part of the option specification
> it ends at the first space.
>
> It seems a bit unfair if sh based commands would not be able to use
> spaces while the build-in ones can.
> As underscores are not used in the UI (at least that was my impression
> so far), I thought that to be a good option.
>
> Do you think a different kind of escaping should be used? Backslashes?
> Or no spaces?

"git merge" also uses equals sign in one of the argument names.  That
would not be possible for sh based commands either.

As a lot of commands are using dashes instead of spaces, so not
supporting spaces is probably fine.

Another option I can think of is to use (or just allow) angle brackets
around argument names.  That would look similar to the actual output.
"git shortlog" has some punctuation in an argument name, which braces
would make a bit easier to read.
This is how an option description would look like then:

OPTION_SPEC="\
...
S,gpg-sign?<key id>     GPG sign commit from "commit"
w?<w[,i1[,i2]]>         "shortlog" option with a complicated argument name
...
"

If there is interest in this, I could code it up and post for discussion.

> [...]