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

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

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

Junio C Hamano wrote:

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?