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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 10, 2014, 19:55 UTC
Message-ID: <xmqqk3c1rfqj.fsf@gitster.dls.corp.google.com>
In-Reply-To: <531D51EC.6050503@gmail.com>

Ilya Bobyr <ilya.bobyr@gmail.com> writes:

Show 13 quoted lines

> On 3/4/2014 11:22 AM, Junio C Hamano wrote:
>> Ilya Bobyr <ilya.bobyr@gmail.com> writes:
>>> @@ -333,6 +339,7 @@ h,help    show the help
>>>     foo       some nifty option --foo
>>>   bar=      some cool option --bar with an argument
>>> +baz=arg   another cool option --baz with an argument named <arg>
>> It probably is better not to have " named <arg>" at the end here, as
>> that gives an apparent-but-false contradiction with the "Angle
>> brackets are added *automatically*" and confuse readers.  At least,
>> it confused _this_ reader.
>
> I am not sure I understand what is confusing here.  But I removed the
> " named <arg>" part.

After reading "Angle brackets are automatically given", seeing that the argument description has manually spelled "<arg>" gave me "Huh?".

Without " named <arg>" there is no such confusion.

> If there would be an example, I think, it is easy to understand how it
> works.

Of course. That is why I suggested to do without " named <arg>" part---I didn't mean to suggest not to add the example. I also think that you can demonstrate something other than '=' (whose usage is already shown with "bar=" above) here as well, but I think we can go either way.

Show 18 quoted lines

>> After the "eval" in the existing example to parse the "$@" argument
>> list in this part of the documentation, it may be a good idea to say
>> something like:
>>
>> 	The above command, when "$@" is "--help", produces the
>> 	following help output:
>>
>> 	... sample output here ...
>>
>> to show the actual output.  That way, we can illustrate how input
>> "baz?arg description of baz" is turned into "--baz[=<arg>]" output
>> clearly (yes, I am suggesting to use '?' in the new example, not '='
>> whose usage is already shown in the existing example).
>
> Documentation on the whole argument parsing is quite short, so, I
> though, adding an example just to show how usage is generated would
> look like I am trying to make this feature look important than it is
> :)

You already are by saying the "Angle brackets are automatic", aren't you?

> At the same time the target structure that holds the option
> description calls this string "argh".

OK, that is fine, then (I'd prefer a field name not to sound like arrrgh, but that is an entirely different topic).

> I've renamed it to "end".  It is used to remember possible end of the
> argument name in just one paragraph of code.

Sounds good.