git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Denton Liu <liu.denton@gmail.com>
Cc: Git Mailing List <git@vger.kernel.org>
Subject: Re: [PATCH] git-submodule.txt: fix AsciiDoc formatting error
Date: Fri, 13 Sep 2019 16:13:23 -0700
Message-ID: <xmqq36gzdc30.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <20190913220902.GA93452@dentonliu-ltm.internal.salesforce.com>

Denton Liu <liu.denton@gmail.com> writes:

>> > -set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>::
>> 
>> I say "almost", as it gives a wrong impression that you can give
>> "-b" without "<branch>" X-<.
>> 
>> Now what does the updated text say to us?
>> 
>> > +set-branch (-d|--default)|(-b|--branch <branch>) [--] <path>::
>> 
>> I think the attempt to cram the short-form is unnecessarily
>> cluttering and making the result incorrect.
>>  ...
>> 
> Hmm, I don't really like this since with every other subcommand, the
> short-forms are in the command summary so it's obvious to the reader
> in a quick glance which options are available.

I actually do not think it adds that much value.  Once a user learns
what --branch does and is told -b is its short form, it is much less
important that -b and --branch are both available than --default and
--branch are possibilities, and you cannot use both at the same time.

If anything, perhaps other subcommands' description may benefit if
we unclutter by reducing the prominence we give to their short form.

> In the context line above, we see `[(-n|--summary-limit) <n>]` as a
> possible way of notating a short and long option with argument. What do
> you think about the following potential output?
>
> 	set-branch (-d|--default)|((-b|--branch) <branch>) [--] <path>::
>
> Of course, we reintroduce the double paren problem but I can dig into
> asciidoc syntax and figure out how to escape it properly.

That's much less important than the fact that you are losing "-b and
-d cannot be used together", which is what the usage string gives us
(and which is what I tried to express with my rewrite).

  reply index

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-10 19:09 Denton Liu
2019-09-13 18:03 ` Junio C Hamano
2019-09-13 22:09   ` Denton Liu
2019-09-13 23:13     ` Junio C Hamano [this message]
2019-09-16 18:19 ` [PATCH v2] " Denton Liu
2019-09-16 19:25   ` Junio C Hamano

Reply instructions:

You may reply publically 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=xmqq36gzdc30.fsf@gitster-ct.c.googlers.com \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    --cc=liu.denton@gmail.com \
    /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

git@vger.kernel.org list mirror (unofficial, one of many)

Archives are clonable:
	git clone --mirror http://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox