From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 03 Nov 2021 16:28:36 GMT
Subject: Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders
Message-ID: <xmqqlf258aq3.fsf@gitster.g>
In-Reply-To: <0b404448-cd4b-8614-2c49-c4683b56879f@gmail.com>

Jean-Noël Avila <avila.jn@gmail.com> writes:

> Junio C Hamano wrote:
>> Jean-Noël AVILA <jn.avila@free.fr> writes:
>>
>>> The choices here may be awkward; no problem to propose even more descriptive 
>>> names.
>>>
>>>>   Similarly "the 'format:<format-string>' format" feels highly
>>>>   redundant, I expect the reader knows that <string> contains a format
>>>>   inside it as it's mentioned immediately before *and* after.
>>>>
>>> The fact that it is a string doesn't tell you much about what you can do with 
>>> it. For me, this isn't a problem that the explanation is redundant.
>> I agree that --format:<string> is quite poor, as type alone does not
>> give readers any information on what it means and how it is supposed
>> to look like.  Calling it <format-string> does make quite a lot of
>> sense.
>>
>> It is a bit less obvious how much value we get out of <bool-value>,
>> though.  In --opt=<arg> scheme of things, what comes after '=' are
>> all <value>s, so <bool-value> does not clarify over <bool> like the
>> way <format-string> clarifies over <string>.
>>
> Agreed. Should reroll the patch series?

I guess another (hopefully the final) reroll would not hurt (but we
are not in hurry---this may be among the topics that graduate early
in the next cycle, but not during this cycle).

Thanks.