Ilya Bobyr <ilya.bobyr@xxxxxxxxx> writes: > On 3/4/2014 11:22 AM, Junio C Hamano wrote: >> Ilya Bobyr <ilya.bobyr@xxxxxxxxx> 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. >> 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html