From: Junio C Hamano Date: Fri, 13 Sep 2019 18:03:39 GMT Subject: Re: [PATCH] git-submodule.txt: fix AsciiDoc formatting error Message-ID: In-Reply-To: <796a25ee1e9a9c0421d42ab6644e81d23a9bd99b.1568142486.git.liu.denton@gmail.com> Denton Liu 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 ) [--] which is, "you can give either --default or --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 )) [--] :: I say "almost", as it gives a wrong impression that you can give "-b" without "" X-<. Now what does the updated text say to us? > +set-branch (-d|--default)|(-b|--branch ) [--] :: 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 )) [--] :: +set-branch (--default|--branch ) [--] :: 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..branch configuration + `--branch` option (or its short-form, `-b `) + allows the remote branch to be specified. The + `--default` option (or its short-form, `-d`) + removes the submodule..branch configuration key, which causes the tracking branch to default to 'master'. summary [--cached|--files] [(-n|--summary-limit) ] [commit] [--] [...]::