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

Hi,

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

Jean-Noël Avila [off-list ref] writes:

quoted

Junio C Hamano wrote:

quoted

Jean-Noël AVILA [off-list ref] writes:

quoted

The choices here may be awkward; no problem to propose even more descriptive
names.

quoted

  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