From: Jean-Noël Avila <avila.jn@gmail.com>
Date: Wed, 03 Nov 2021 12:46:39 GMT
Subject: Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders
Message-ID: <0b404448-cd4b-8614-2c49-c4683b56879f@gmail.com>
In-Reply-To: <xmqqmtmocqz4.fsf@gitster.g>

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?