Re: [PATCH] git-submodule.txt: fix AsciiDoc formatting error
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Sep 13, 2019, 18:03 UTC
- Message-ID
- <xmqqk1acdqf8.fsf@gitster-ct.c.googlers.com>
- In-Reply-To
- <796a25ee1e9a9c0421d42ab6644e81d23a9bd99b.1568142486.git.liu.denton@gmail.com>
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>...]::