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

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