Alex Henrie [off-list ref] writes:
2015-10-16 11:42 GMT-06:00 Junio C Hamano [off-list ref]:
quoted
Yes, but that fixes historical "mistake", no?
With this, you are breaking historical practice by changing only one
instance to deviate from the then-current practice of saying
'options' without brackets. It is based on the point of view that
considers anything inside <bracket> and a fixed string 'options' are
meant to be replaced by intelligent readers, which is as valid as
the more recent practice to consider only things inside <bracket>
are placeholders.
OK, I see. You're saying that it's OK to fix typos and grammatical
errors in contrib/examples, but it's not okay to modernize the
scripts' designs.
Please read it again, look at contrib/examples and realize that that
is not what I said at all.
This is not about modern vs old-school. The reason why the part of
the patch to contrib/ under discussion is wrong is because of
(in)consistency.
Look at the output from "git grep option contrib/examples/" and
notice that in the old days, these scripted Porcelains consistently
said "[options]" without "<bracket>".
It would have been a different matter if the patch _were_ to update
all "[options]" to "[<options>]" in contrib/examples/ consistently,
and such a patch might have even been an improvement, especially if
the modern style were clearly superiour than the old-school style
(which is not, by they way [*1*]).
But that is not what the patch did. It turned only one of them into
"[<options>]", making the single instance inconsistent from all the
others around it. That is why it was wrong.
[Footnote]
*1* The "modern" style is not necessarily an improvement, by the
way. The way we specify that a "thing" in the help text is a
placeholder and that there may be more instances of the same
"thing" is to say "[<thing>...]", but in your "modernized" form,
unlike all the other usual "things", possibly multiple options
are spelled "[<options>]" without having ellipses at the end,
which is an oddball. If we are to treat options specially like
that anyway, intelligent readers can read an "old-school"
description "[options]" and understand that that token stands
for possibly multiple options just fine, and all we have gained
by going to the "modernized" form is to waste two characters for
<brackets>.
I am not saying that we should not apply the other half of the
patch that makes builtin/pull.c say "[<options>]". These days,
many other commands nearby (i.e. the "modern" ones) do use that
form consistently, so it is an improvement.
2015-10-19 23:17 GMT-06:00 Junio C Hamano [off-list ref]:
Alex Henrie [off-list ref] writes:
quoted
2015-10-16 11:42 GMT-06:00 Junio C Hamano [off-list ref]:
quoted
Yes, but that fixes historical "mistake", no?
With this, you are breaking historical practice by changing only one
instance to deviate from the then-current practice of saying
'options' without brackets. It is based on the point of view that
considers anything inside <bracket> and a fixed string 'options' are
meant to be replaced by intelligent readers, which is as valid as
the more recent practice to consider only things inside <bracket>
are placeholders.
OK, I see. You're saying that it's OK to fix typos and grammatical
errors in contrib/examples, but it's not okay to modernize the
scripts' designs.
Please read it again, look at contrib/examples and realize that that
is not what I said at all.
This is not about modern vs old-school. The reason why the part of
the patch to contrib/ under discussion is wrong is because of
(in)consistency.
Look at the output from "git grep option contrib/examples/" and
notice that in the old days, these scripted Porcelains consistently
said "[options]" without "<bracket>".
It would have been a different matter if the patch _were_ to update
all "[options]" to "[<options>]" in contrib/examples/ consistently,
and such a patch might have even been an improvement, especially if
the modern style were clearly superiour than the old-school style
(which is not, by they way [*1*]).
But that is not what the patch did. It turned only one of them into
"[<options>]", making the single instance inconsistent from all the
others around it. That is why it was wrong.
I understand now, thanks. I really appreciate your commitment to being
consistent.
[Footnote]
*1* The "modern" style is not necessarily an improvement, by the
way. The way we specify that a "thing" in the help text is a
placeholder and that there may be more instances of the same
"thing" is to say "[<thing>...]", but in your "modernized" form,
unlike all the other usual "things", possibly multiple options
are spelled "[<options>]" without having ellipses at the end,
which is an oddball. If we are to treat options specially like
that anyway, intelligent readers can read an "old-school"
description "[options]" and understand that that token stands
for possibly multiple options just fine, and all we have gained
by going to the "modernized" form is to waste two characters for
<brackets>.
I am not saying that we should not apply the other half of the
patch that makes builtin/pull.c say "[<options>]". These days,
many other commands nearby (i.e. the "modern" ones) do use that
form consistently, so it is an improvement.
I pushed to change [options] to [<options>] because even if the angle
brackets don't help new users or translators in this particular case,
the angle brackets encourage Git authors to use angle brackets when
writing commands that are not so easy to understand. If you think that
[<option>...] is better because it is even more consistent, I would be
happy to send a patch to make that change.
Anyway, thanks again for your attention to detail.
-Alex