Junio C Hamano wrote:
> Jari Aalto <jari.aalto@xxxxxxxxx> writes:
>
>> * Sun 2008-02-03 Jakub Narebski <jnareb@xxxxxxxxx> 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
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
