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

From: Johannes Schindelin <Johannes.Schindelin@gmx.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Jean-Noël Avila" <avila.jn@gmail.com>,
	"Jean-Noël AVILA" <jn.avila@free.fr>,
	"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: Thu, 4 Nov 2021 01:38:03 +0100 (CET)	[thread overview]
Message-ID: <nycvar.QRO.7.76.6.2111040134110.56@tvgsbejvaqbjf.bet> (raw)
In-Reply-To: <xmqqlf258aq3.fsf@gitster.g>

[-- Attachment #1: Type: text/plain, Size: 2189 bytes --]

Hi,

On Wed, 3 Nov 2021, Junio C Hamano wrote:

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

I fear that it won't be as easy to send the next iteration as one might
think: GitGitGadget works off of open Pull Requests on GitHub. And the
branch for the Pull Request corresponding to this series has been deleted,
thereby permanently closing the Pull Request (it cannot be reopened
anymore): https://github.com/gitgitgadget/git/pull/1066#event-5541689437

That means that none of GitGitGadget's convenience can be used to send v3
with a range-diff. All that can be done at this point is to open a new
Pull Request, generate a range-diff manually (which could very easily
differ from the actual range-diff, whether by design or mistake) and put
it into the cover letter, then send a "v3" (which is actually a v1).

Ciao,
Johannes