git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / Atom feed
* [PATCH] git-submodule.txt: fix AsciiDoc formatting error
@ 2019-09-10 19:09 Denton Liu
  2019-09-13 18:03 ` Junio C Hamano
  0 siblings, 1 reply; 4+ messages in thread
From: Denton Liu @ 2019-09-10 19:09 UTC (permalink / raw)
  To: Git Mailing List

In b57e8119e6 (submodule: teach set-branch subcommand, 2019-02-08), the
`set-branch` subcommand was added for submodules. When the documentation
was written, the syntax for a "index term" in AsciiDoc was
accidentally used. This caused the documentation to be rendered as

	set-branch -d|--default)|(-b|--branch <branch> [--] <path>

instead of

	set-branch (-d|--default)|(-b|--branch <branch>) [--] <path>

Remove surrounding parentheses so that the "index term" syntax is not
triggered (and because it looks nicer without them anyway ;) ).

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-submodule.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 0ed5c24dc1..e349442f4c 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -173,7 +173,7 @@ submodule with the `--init` option.
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 --
-set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>::
+set-branch (-d|--default)|(-b|--branch <branch>) [--] <path>::
 	Sets the default remote tracking branch for the submodule. The
 	`--branch` option allows the remote branch to be specified. The
 	`--default` option removes the submodule.<name>.branch configuration
-- 
2.23.0.163.g796a25ee1e


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] git-submodule.txt: fix AsciiDoc formatting error
  2019-09-10 19:09 [PATCH] git-submodule.txt: fix AsciiDoc formatting error Denton Liu
@ 2019-09-13 18:03 ` Junio C Hamano
  2019-09-13 22:09   ` Denton Liu
  0 siblings, 1 reply; 4+ messages in thread
From: Junio C Hamano @ 2019-09-13 18:03 UTC (permalink / raw)
  To: Denton Liu; +Cc: Git Mailing List

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

> Remove surrounding parentheses so that the "index term" syntax is not
> triggered (and because it looks nicer without them anyway ;) ).

"Correct" always trumps "nicer", though ;-)

The $USAGE string in the script describes the available options to
this subcommand like so:

    or: $dashless [--quiet] set-branch (--default|--branch <branch>) [--] <path>

which is, "you can give either --default or --branch <branch>, but
not both".  What the original, if there were no special meaning in
double-paren, meant to say seems to (almost) match that.

> -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.  How about doing
something like this instead?

 Documentation/git-submodule.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 0ed5c24dc1..816baa7dd0 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -173,10 +173,12 @@ submodule with the `--init` option.
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 --
-set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>::
+set-branch (--default|--branch <branch>) [--] <path>::
 	Sets the default remote tracking branch for the submodule. The
-	`--branch` option allows the remote branch to be specified. The
-	`--default` option removes the submodule.<name>.branch configuration
+	`--branch` option (or its short-form, `-b <branch>`)
+	allows the remote branch to be specified. The
+	`--default` option (or its short-form, `-d`)
+	removes the submodule.<name>.branch configuration
 	key, which causes the tracking branch to default to 'master'.
 
 summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] git-submodule.txt: fix AsciiDoc formatting error
  2019-09-13 18:03 ` Junio C Hamano
@ 2019-09-13 22:09   ` Denton Liu
  2019-09-13 23:13     ` Junio C Hamano
  0 siblings, 1 reply; 4+ messages in thread
From: Denton Liu @ 2019-09-13 22:09 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: Git Mailing List

On Fri, Sep 13, 2019 at 11:03:39AM -0700, Junio C Hamano wrote:
> Denton Liu <liu.denton@gmail.com> writes:
> 
> > Remove surrounding parentheses so that the "index term" syntax is not
> > triggered (and because it looks nicer without them anyway ;) ).
> 
> "Correct" always trumps "nicer", though ;-)
> 
> The $USAGE string in the script describes the available options to
> this subcommand like so:
> 
>     or: $dashless [--quiet] set-branch (--default|--branch <branch>) [--] <path>
> 
> which is, "you can give either --default or --branch <branch>, but
> not both".  What the original, if there were no special meaning in
> double-paren, meant to say seems to (almost) match that.
> 
> > -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.  How about doing
> something like this instead?
> 
>  Documentation/git-submodule.txt | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index 0ed5c24dc1..816baa7dd0 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -173,10 +173,12 @@ submodule with the `--init` option.
>  If `--recursive` is specified, this command will recurse into the
>  registered submodules, and update any nested submodules within.
>  --
> -set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>::
> +set-branch (--default|--branch <branch>) [--] <path>::
>  	Sets the default remote tracking branch for the submodule. The
> -	`--branch` option allows the remote branch to be specified. The
> -	`--default` option removes the submodule.<name>.branch configuration
> +	`--branch` option (or its short-form, `-b <branch>`)
> +	allows the remote branch to be specified. The
> +	`--default` option (or its short-form, `-d`)
> +	removes the submodule.<name>.branch configuration
>  	key, which causes the tracking branch to default to 'master'.
>  
>  summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::

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. With this change, a
reader would have to not only read the summary line but also scan the
blurb below.

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.

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] git-submodule.txt: fix AsciiDoc formatting error
  2019-09-13 22:09   ` Denton Liu
@ 2019-09-13 23:13     ` Junio C Hamano
  0 siblings, 0 replies; 4+ messages in thread
From: Junio C Hamano @ 2019-09-13 23:13 UTC (permalink / raw)
  To: Denton Liu; +Cc: Git Mailing List

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-09-10 19:09 [PATCH] git-submodule.txt: fix AsciiDoc formatting error 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

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

Archives are clonable:
	git clone --mirror https://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