From: Junio C Hamano <gitster@pobox.com>
To: Ilya Bobyr <ilya.bobyr@gmail.com>
Cc: git@vger.kernel.org, Jeff King <peff@peff.net>,
Jonathan Nieder <jrnieder@gmail.com>
Subject: Re: [PATCH] rev-parse --parseopt: option argument name hints
Date: Mon, 10 Mar 2014 12:55:00 -0700 [thread overview]
Message-ID: <xmqqk3c1rfqj.fsf@gitster.dls.corp.google.com> (raw)
In-Reply-To: <531D51EC.6050503@gmail.com> (Ilya Bobyr's message of "Sun, 09 Mar 2014 22:47:24 -0700")
Ilya Bobyr <ilya.bobyr@gmail.com> writes:
> 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.
>> 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.
next prev parent reply other threads:[~2014-03-10 19:55 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-03-03 10:32 [PATCH] rev-parse --parseopt: option argument name hints Ilya Bobyr
2014-03-04 19:22 ` Junio C Hamano
2014-03-10 5:47 ` Ilya Bobyr
2014-03-10 5:55 ` [PATCH v2] " Ilya Bobyr
2014-03-10 19:55 ` Junio C Hamano [this message]
2014-03-11 19:10 ` [PATCH] " Junio C Hamano
2014-03-12 7:26 ` Ilya Bobyr
2014-03-12 16:59 ` Junio C Hamano
2014-03-19 9:02 ` Ilya Bobyr
2014-03-19 18:46 ` Junio C Hamano
2014-03-20 8:38 ` Ilya Bobyr
2014-03-20 8:44 ` [PATCH v3] " Ilya Bobyr
2014-03-20 18:38 ` Junio C Hamano
2014-03-20 23:19 ` Ilya Bobyr
2014-03-21 7:55 ` Ilya Bobyr
2014-03-21 17:04 ` Junio C Hamano
2014-03-22 9:47 ` [PATCH v4] " Ilya Bobyr
2014-03-24 17:52 ` [PATCH 0/3] Parse-options: spell multi-word placeholders with dashes Junio C Hamano
2014-03-24 17:52 ` [PATCH 1/3] parse-options: multi-word argh should use dash to separate words Junio C Hamano
2014-03-24 17:52 ` [PATCH 2/3] update-index: teach --cacheinfo a new syntax "mode,sha1,path" Junio C Hamano
2014-03-24 17:52 ` [PATCH 3/3] parse-options: make sure argh string does not have SP or _ Junio C Hamano
2014-03-20 20:18 ` [PATCH v3] rev-parse --parseopt: option argument name hints Eric Sunshine
2014-03-21 3:38 ` Ilya Bobyr
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqk3c1rfqj.fsf@gitster.dls.corp.google.com \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=ilya.bobyr@gmail.com \
--cc=jrnieder@gmail.com \
--cc=peff@peff.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).