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

Ilya Bobyr [off-list ref] writes:

On 3/4/2014 11:22 AM, Junio C Hamano wrote:

quoted

Ilya Bobyr [off-list ref] writes:

quoted

@@ -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.

quoted

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.