Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders

From: Junio C Hamano <gitster@pobox.com>
To: "Jean-Noël AVILA" <jn.avila@free.fr>
Cc: "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>,
	git@vger.kernel.org, "Eli Schwartz" <eschwartz@archlinux.org>,
	"Martin Ågren" <martin.agren@gmail.com>,
	"Eric Sunshine" <sunshine@sunshineco.com>
Subject: Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders
Date: Sun, 31 Oct 2021 23:47:11 -0700	[thread overview]
Message-ID: <xmqqmtmocqz4.fsf@gitster.g> (raw)
In-Reply-To: <2803948.JoDkH9avOM@cayenne> (=?utf-8?Q?=22Jean-No=C3=ABl?= AVILA"'s message of "Sun, 31 Oct 2021 21:23:11 +0100")

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