From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 30 Sep 2022 21:28:41 GMT
Subject: Re: [PATCH v3 07/36] doc SYNOPSIS & -h: fix incorrect alternates syntax
Message-ID: <xmqq1qrsa6wm.fsf@gitster.g>
In-Reply-To: <patch-v3-07.36-829bdf58499-20220930T180415Z-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> 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.

It depends on which way you look at it ;-) namely, if vertical bar
binds tighter than option and its argument, then "-m|--message
<message>" and "(-m|--message) <message>" would mean the same thing.

Later in the series, we start insisting that the vertical bar must
have SP on both of its sides, which makes the vertical bar less
tightly binding visually, and at that point, adding parentheses
around the choices does become needed.

As long as these become consistent, the end result is happier than
the status quo.

> -	     [-u|--include-untracked] [-a|--all] [-m|--message <message>]
> +	     [-u|--include-untracked] [-a|--all] [(-m|--message) <message>]
> -'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
> +'git stash' store [(-m|--message) <message>] [-q|--quiet] <commit>

Thanks.