[PATCH v2] doc/git-bisect: clarify `git bisect run` syntax

From: Javier Mora <cousteaulecommandant@gmail.com>

The description of the `git bisect run` command syntax at the beginning of the manpage is `git bisect run <cmd>...`, which isn't quite clear about what `<cmd>` is or what the `...` mean; one could think that it is the whole (quoted) command line with all arguments in a single string, or that it supports multiple commands, or that it doesn't accept commands with arguments at all.

Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax, in both the manpage and the `git bisect -h` command output.

Additionally, change `--term-{new,bad}` et al to `--term-(new|bad)` for consistency with the synopsis syntax conventions.

Signed-off-by: Javier Mora <cousteaulecommandant@gmail.com>
---
    doc/git-bisect: clarify git bisect run syntax
    
    I saw someone in IRC wondering about the syntax for git bisect run for a
    command with arguments, and found that its short description at the
    beginning of the manpage is not very clear (although it gets clarified
    later when it is properly described). It describes the syntax as git
    bisect run <cmd>... which is a bit confusing; it should say git bisect
    run <cmd> [<arg>...], otherwise it somehow looks like you have to "enter
    one or more commands", and that each command is a single argument.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1602%2Fcousteaulecommandant%2Fman-git-bisect-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1602/cousteaulecommandant/man-git-bisect-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1602

Range-diff vs v1:

 1:  ce4c60a6f4f ! 1:  8de70bb060e doc/git-bisect: clarify `git bisect run` syntax
     @@ Commit message
          or that it supports multiple commands, or that it doesn't accept
          commands with arguments at all.
      
     -    Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax.
     +    Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax,
     +    in both the manpage and the `git bisect -h` command output.
     +
     +    Additionally, change `--term-{new,bad}` et al to `--term-(new|bad)`
     +    for consistency with the synopsis syntax conventions.
      
          Signed-off-by: Javier Mora <cousteaulecommandant@gmail.com>
      
       ## Documentation/git-bisect.txt ##
     +@@ Documentation/git-bisect.txt: DESCRIPTION
     + The command takes various subcommands, and different options depending
     + on the subcommand:
     + 
     +- git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
     ++ git bisect start [--term-(new|bad)=<term-new> --term-(old|good)=<term-old>]
     + 		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
     +  git bisect (bad|new|<term-new>) [<rev>]
     +  git bisect (good|old|<term-old>) [<rev>...]
      @@ Documentation/git-bisect.txt: on the subcommand:
        git bisect (visualize|view)
        git bisect replay <logfile>
     @@ Documentation/git-bisect.txt: on the subcommand:
        git bisect help
       
       This command uses a binary search algorithm to find which commit in
     +
     + ## builtin/bisect.c ##
     +@@ builtin/bisect.c: static GIT_PATH_FUNC(git_path_bisect_first_parent, "BISECT_FIRST_PARENT")
     + static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
     + 
     + #define BUILTIN_GIT_BISECT_START_USAGE \
     +-	N_("git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]" \
     ++	N_("git bisect start [--term-(new|bad)=<term> --term-(old|good)=<term>]" \
     + 	   "    [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]" \
     + 	   "    [<pathspec>...]")
     + #define BUILTIN_GIT_BISECT_STATE_USAGE \
     +@@ builtin/bisect.c: static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
     + #define BUILTIN_GIT_BISECT_LOG_USAGE \
     + 	"git bisect log"
     + #define BUILTIN_GIT_BISECT_RUN_USAGE \
     +-	N_("git bisect run <cmd>...")
     ++	N_("git bisect run <cmd> [<arg>...]")
     + 
     + static const char * const git_bisect_usage[] = {
     + 	BUILTIN_GIT_BISECT_START_USAGE,

 Documentation/git-bisect.txt | 4 ++--
 builtin/bisect.c             | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)