Alex Henrie <alexhenrie24@xxxxxxxxx> writes:
> 2015-10-16 11:42 GMT-06:00 Junio C Hamano <gitster@xxxxxxxxx>:
>>
>> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html