From: Jakub Narebski <jnareb@gmail.com>
Date: Mon, 04 Feb 2008 10:15:20 GMT
Subject: Re: [PATCH] git-rebase.sh: Update USAGE string (No. 1)
Message-ID: <200802041115.22409.jnareb@gmail.com>
In-Reply-To: <7vfxw9pnbp.fsf@gitster.siamese.dyndns.org>

Junio C Hamano wrote:
> 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] ...

BTW. it is not only cpio and rpm, but also combinediff (and friends from 
patchutils), flex, gimp, jpegtopnm (and other from netpbm), ps2pdf, 
run, tail, xmlto, ip, losetup, netstat, sudo and sudoedit,...

> 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

Actually we are not entirely consistent here.  git-init(1) has 
  --shared[={false|true|umask|group|all|world|everybody}]
in the option description, git-rev-list(1) has
  [ --date={local|relative|default|iso|rfc|short} ]
in its longish synopsis (although in second case we could omit
the curlies, it is in separate line so reducing line length does
not matter in this case).

> (3) it is a thankless makework to replace them all to {} _and
> make sure the conversion is correct_ (large con).  

All true.

> (4) also if 
> other people make changes to documentation at the same time,
> that would add more work in conflict resolution (slight con).

Well, we sould have to document this in CodingStyle, I think, then.
 
> 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...

It probably also depends if we deperately want to reduce line length as 
not to split synopsis into yet another line (the shorter synopsis is, 
usually the better).

-- 
Jakub Narebski
Poland