Subject: Re: [PATCH v3 11/36] doc txt & -h consistency: fix incorrect alternates syntax

From: Junio C Hamano <[email-masked]>
Date: Fri, 30 Sep 2022 18:09:02 -0700

Ævar Arnfjörð Bjarmason  <[email-masked]> writes:

> Fix the incorrect "[-o | --option <argument>]" syntax, which should be
> "[(-o | --option) <argument>]", we were previously claiming that only
> the long option accepted the "<argument>", which isn't what we meant.
>
> This syntax issue for "bugreport" originated in
> 238b439d698 (bugreport: add tool to generate debugging info,
> 2020-04-16), and for "diagnose" in 6783fd3cef0 (builtin/diagnose.c:
> create 'git diagnose' builtin, 2022-08-12), which copied and adjusted
> "bugreport" documentation and code.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <[email-masked]>
> ---
>  builtin/bugreport.c | 2 +-
>  builtin/diagnose.c  | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)

I think we saw exactly the same pattern in an earlier step.  If the
patches in this series are split along the type of fix, then these
two and the other patch fall into the same category.  Another way to
organize is to split per file boundary, but I think these two paths
are fixed up for different problem in later steps.  I think split
along the type of fix makes much more sense, if we can, than split
per file, so I am almost OK with the current organization (probably
with this squashed into that earlier step).

> diff --git a/builtin/bugreport.c b/builtin/bugreport.c
> index faa268f3cfb..23170113cc8 100644
> --- a/builtin/bugreport.c
> +++ b/builtin/bugreport.c
> @@ -60,7 +60,7 @@ static void get_populated_hooks(struct strbuf *hook_info, int nongit)
>  }
>  
>  static const char * const bugreport_usage[] = {
> -	N_("git bugreport [-o|--output-directory <file>] [-s|--suffix <format>]\n"
> +	N_("git bugreport [(-o|--output-directory) <file>] [(-s|--suffix) <format>]\n"
>  	   "              [--diagnose[=<mode>]"),
>  	NULL
>  };
> diff --git a/builtin/diagnose.c b/builtin/diagnose.c
> index 28c394a62a5..474de9ec647 100644
> --- a/builtin/diagnose.c
> +++ b/builtin/diagnose.c
> @@ -3,7 +3,7 @@
>  #include "diagnose.h"
>  
>  static const char * const diagnose_usage[] = {
> -	N_("git diagnose [-o|--output-directory <path>] [-s|--suffix <format>]\n"
> +	N_("git diagnose [(-o|--output-directory) <path>] [(-s|--suffix) <format>]\n"
>  	   "             [--mode=<mode>]"),
>  	NULL
>  };