Re: [PATCH v2 01/35] CodingGuidelines: update and clarify command-line conventions

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 30, 2022, 17:09 UTC
Message-ID: <xmqqzgegkcwb.fsf@gitster.g>
In-Reply-To: <xmqqpmffv24a.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 24 quoted lines

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>>   Optional parts are enclosed in square brackets:
>> -   [<extra>]
>> -   (Zero or one <extra>.)
>> +   [<file>...]
>> +   (Zero or more of <file>.)
>
> OK.
>
>> + Use spacing around "|" token(s), but not immediately after opening or
>> + before closing a [] or () pair:
>> +   Do: [-q | --quiet]
>> +   Don't: [-q|--quiet]
>> +
>> + Don't use spacing around "|" tokens when they're used to seperate the
>> + alternate arguments of an option:
>> +    Do: --track[=(direct|inherit)]
>> +    Don't: --track[=(direct | inherit)]
>> +
>
> Hmph, that sounds inconsistent; I would have expected the same use
> (or omission) of space around the vertical bar.  But if that is the
> prevailing style, I won't complain about writing it down.

Perhaps in order to avoid "Huh? isn't that inconsistent?" knee-jerk reaction, it may be a good idea to explain the reason why?

I am guessing that the difference between the two has something to do with the desire to make it compact when it appears as a "value" for something (signalled after a "=" sign), but (1) I am not sure if you share the reasoning, and more importantly (2) I am failing to come up with a concise way to phrase it.

Thanks.