Re: [PATCH] pull: add angle brackets to usage string

[Junio C Hamano <gitster@pobox.com>]

Alex Henrie <alexhenrie24@gmail.com> writes:

> 2015-10-16 11:42 GMT-06:00 Junio C Hamano <gitster@pobox.com>:
>>
>> 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.