Re: [PATCH] git-rebase.sh: Update USAGE string (No. 1)

From: Jakub Narebski <jnareb@gmail.com>
Date: Feb 4, 2008, 10:15 UTC
Message-ID: <200802041115.22409.jnareb@gmail.com>
In-Reply-To: <7vfxw9pnbp.fsf@gitster.siamese.dyndns.org>

Junio C Hamano wrote:

Show 10 quoted lines

> 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,...

Show 10 quoted lines

> 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.

Show 5 quoted lines

> 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