Re: [PATCH] git-rebase.sh: Update USAGE string (No. 1)
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Feb 4, 2008, 00:39 UTC
- Message-ID
- <7vfxw9pnbp.fsf@gitster.siamese.dyndns.org>
- In-Reply-To
- <zluh1sxv.fsf@blue.sea.net>
Jari Aalto <jari.aalto@cante.net> writes:
Show 8 quoted lines
> * 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...