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

On 3/20/2014 4:19 PM, Ilya Bobyr wrote:

On 3/20/2014 11:38 AM, Junio C Hamano wrote:

quoted

Ilya Bobyr [off-list ref] writes:

quoted

[...]
    ------------
-<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.

[...]