From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 04 Feb 2008 00:39:06 GMT
Subject: Re: [PATCH] git-rebase.sh: Update USAGE string (No. 1)
Message-ID: <7vfxw9pnbp.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <zluh1sxv.fsf@blue.sea.net>

Jari Aalto <jari.aalto@cante.net> writes:

> * Sun 2008-02-03 Jakub Narebski <jnareb@gmail.com> INBOX
>> I would say "[--whitespace=<option>]" or "[--whitespace=<action>]"
>> instead of introducing yet not agreed upon notation (this has the
>> advantage of shortening synopisis, which should be short IMHO).
>
> The "{a|b|c}" is a used syntax. See cpio(1).
>  
>     cpio  {-o|--create} [-0acvABLV] ...

I do not think using {} for grouping is incorrect, and I think
there is at least a consensus on the list that it is Ok as long
as we consistently do so.

Unfortunately, the majority of, if not all of, our existing
documents use () instead for that purpose.

So pros-and-cons are that (1) changing all of them to use {} is
more politically correct (pro); (2) our use of (), as we
consistently use them, does not hurt readability (neutral); and
(3) it is a thankless makework to replace them all to {} _and
make sure the conversion is correct_ (large con).  (4) also if
other people make changes to documentation at the same time,
that would add more work in conflict resolution (slight con).

As you seem to have volunteered to do the conversion and
validation, I do not see much problem to move from () to {} in
principle.

About the part your patch touches, [--whitespace={a|b|c}] is
more precise than [--whitespace=a|b|c] Jakub suggested, but I
suspect most sane people would not misinterpret the latter as
"this part can be omitted but you could write '--whitespace=a',
'b' or 'c' here", so...